Webhooks

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

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.

Webhook events

All webhook payloads use a standard body based on CloudEvents (opens in a new tab).

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}
    }
  }
}

Jobs

MediaKind.JobStarted

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

MediaKind.JobFinished

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

Streaming locators

MediaKind.StreamingLocatorCreated

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

Scheduled operations

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.

MediaKind.ScheduledOperationOngoing

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

MediaKind.ScheduledOperationCompleted

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