Webhook notifications allow you to receive HTTP requests when specific events occur in MK.IO. For example, when a transcode job finishes, a notification can be sent to a designated endpoint with the details of the job.

You can configure webhook notifications by creating a set of rules, selecting the events you want to receive, and specifying the endpoint details, including any required headers or query parameters.

Configuring webhooks

You can configure endpoints and associate specific events with them using rules. Each webhook rule includes:

• The target URL for the HTTP request
• Custom headers (e.g. authentication tokens)
• A list of events to send to the endpoint

Example rule

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

In the example above:

1. The configuration is enabled,
2. Any events of type MediaKind.JobStarted or MediaKind.JobFinished will cause this webhook rule to fire,
3. A POST request will be made to https://api.example.com/webhooks?process=123456 with the Authorization header included in the request.

Query parameters can be set in spec.queryParams or spec.authentication.queryParams, while HTTP headers can be set in spec.headers or spec.authentication.headers. The ones under the authentication section are not returned when you read the rule back; instead, you see a string of asterisks, protecting your token information from other users.

API endpoints

Please see our API reference for details of the endpoints to create, edit and remove webhook rules.

Webhook events

Standard data format

Our webhooks use a standard body based upon Cloud Events .

{
  "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

Please see our documentation on Jobs.

MediaKind.JobStarted

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

MediaKind.JobFinished

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

Streaming Locators

Please see our documentation on Streaming Locators.

MediaKind.StreamingLocatorCreated

This event is sent once a new streaming locator has been successfully created and can be used.

Scheduled Operations

Please see our documentation on Scheduled Operations (if this feature is available to your organization)

MediaKind.ScheduledOperationAccepted

This event is sent once a new scheduled operation has been accepted by the scheduling engine. Initial checks have been passed, and the operation should be performed as requested.

MediaKind.ScheduledOperationOngoing

This event is sent once the scheduling engine has begun processing a scheduled operation. This event should occur before the any scheduled time on the operation.

MediaKind.ScheduledOperationCompleted

This event is sent once the scheduling engine has completed processing a scheduled operation. This event should occur before the any scheduled time on the operation.