Webhooks

Webhooks let you receive HTTP POST requests when specific events occur in MK.IO, such as a completed transcode job. You configure rules that define which events to watch and where to send the notifications.

Configure webhook rules through the Management API. The MK.IO portal does not provide webhook-rule configuration.

Configure a webhook rule

Each webhook rule specifies:

The target URL for the HTTP POST request.
Custom headers (for example, an authentication token).
Query parameters to append to the request URL.
A list of event types that trigger the rule.

Example rule

{
  "spec": {
    "enabled": true,
    "url": "https://api.example.com/webhooks",
    "authentication": {
      "headers": {
        "Authorization": "Bearer mytoken1234"
      }
    },
    "queryParams": {
      "process": "123456"
    },
    "events": [
      "MediaKind.JobStarted",
      "MediaKind.JobFinished"
    ]
  }
}

This rule is enabled and fires on MediaKind.JobStarted and MediaKind.JobFinished events. MK.IO sends a POST request to https://api.example.com/webhooks?process=123456 with the Authorization header included.

Query parameters can be set in spec.queryParams or spec.authentication.queryParams. HTTP headers can be set in spec.headers or spec.authentication.headers. Fields under the authentication section are write-only. When you read the rule back, those values appear as asterisks to protect your credentials from other users.

API reference

See the webhook rules API reference for endpoints to create, edit, and remove rules.

Delivery behavior

Webhook delivery runs separately from the operation that changes the resource, so a notification may not arrive immediately. MK.IO retries failed deliveries. Build the receiving endpoint to process duplicate deliveries safely and inspect the rule’s event history when troubleshooting.

Webhooks report the supported lifecycle events listed below. They do not notify you about every change to a resource.

Webhook events

All webhook payloads use a standard body based on CloudEvents.

Standard data format

{
  "specversion": "1.0",
  "id": "{unique_id}",
  "type": "{webhook_type}",
  "source": "{object_url}",
  "time": "{event_time}",
  "datacontenttype": "application/json",
  "data": {
    "projectName": "{project_name}",
    "previousState": "{value of state before this event}",
    "state": "{new value of state}",
    "resource": {
      # The contents of the object, as if you had done a GET on {object_url}
    }
  }
}

The resource field contains the full object as returned by a GET request on {object_url}. The comment above is illustrative and is not valid JSON.

Jobs

MediaKind.JobStarted

This event fires when a job is removed from the queue and begins processing.

Field	Value
`.source`	`/api/v1/projects/{project_name}/transforms/{transform_name}/jobs/{job_name}`
`.data.previousState`	`Queued`
`.data.state`	`Processing`

MediaKind.JobFinished

This event fires when a job completes, whether successfully or not.

Field	Value
`.source`	`/api/v1/projects/{project_name}/transforms/{transform_name}/jobs/{job_name}`
`.data.previousState`	`Processing`
`.data.state`	`Canceled \| Error \| Finished`

Streaming locators

MediaKind.StreamingLocatorCreated

This event fires once a new streaming locator has been successfully created and is ready to use.

Field	Value
`.source`	`/api/v1/projects/{project_name}/media/streamingLocators/{locator_name}`
`.data.previousState`	`Creating`
`.data.state`	`Created`

Scheduled operations

Scheduled operations events are only available if this feature is enabled for your organization.

MediaKind.ScheduledOperationAccepted

This event fires once a new scheduled operation has been accepted by the scheduling engine. Initial checks have passed and the operation will proceed as requested.

Field	Value
`.source`	`/api/v1/projects/{project_name}/.../scheduledOperations/{scheduled_operation_name}`
`.data.previousState`	`Pending`
`.data.state`	`Accepted`

MediaKind.ScheduledOperationOngoing

This event fires once the scheduling engine begins processing a scheduled operation.

Field	Value
`.source`	`/api/v1/projects/{project_name}/.../scheduledOperations/{scheduled_operation_name}`
`.data.previousState`	`Accepted`
`.data.state`	`Ongoing`

MediaKind.ScheduledOperationCompleted

This event fires once the scheduling engine finishes processing a scheduled operation.

Field	Value
`.source`	`/api/v1/projects/{project_name}/.../scheduledOperations/{scheduled_operation_name}`
`.data.previousState`	`Ongoing`
`.data.state`	`Completed`

Configure webhooks with the API

Use the Webhooks API Guide for the rule lifecycle and a complete create, list, and delete workflow.