Webhook rules

This guide covers the management side of webhooks: creating rules, updating them, and reading delivery history. For the event model and the delivered payload shape, see Webhooks.

Each rule is project-scoped and identified by a stable name in the URL. The practical pattern is to name the rule for its purpose, create or update it with PUT, read it back to confirm the non-secret configuration, and inspect its /events history when debugging delivery.

Create or update a rule

A rule is created or replaced with PUT at its name. The spec requires enabled, url, and events. Put secrets in authentication.headers or authentication.queryParams, which are write-only; put non-sensitive decoration in the top-level headers and `queryParams.

curl -X PUT "https://app.mk.io/api/v1/projects/<PROJECT_NAME>/webhook/rules/job-notifications" \

-H "Authorization: Bearer <YOUR_TOKEN>" \

-H "Content-Type: application/json" \

-d '{

"spec": {

"url": "https://your-endpoint.example.com/webhook",

"enabled": true,

"events": ["MediaKind.JobStarted", "MediaKind.JobFinished"],

"authentication": {

"headers": { "X-Webhook-Secret": "<SHARED_SECRET>" }

},

"headers": { "X-Source": "mkio" }

}

}'

Because PUT replaces the whole rule, include the full spec each time. To pause delivery without losing the rule, send the same PUT with enabled set to `false.

Read the rule

curl -X GET "https://app.mk.io/api/v1/projects/<PROJECT_NAME>/webhook/rules" \

-H "Authorization: Bearer <YOUR_TOKEN>"

curl -X GET "https://app.mk.io/api/v1/projects/<PROJECT_NAME>/webhook/rules/job-notifications" \

-H "Authorization: Bearer <YOUR_TOKEN>"

Authentication values read back masked, so use the read response to confirm the structure, enabled state, URL, events, and non-secret headers, not the secrets themselves.

Inspect delivery history

When an application reports a missing event, the rule’s events collection is the first place to look:

curl -X GET "https://app.mk.io/api/v1/projects/<PROJECT_NAME>/webhook/rules/job-notifications/events" \

-H "Authorization: Bearer <YOUR_TOKEN>"

Each record carries created, source, type, and a status of Pending, Retrying, Failed, or Sent. A Failed or stuck Retrying status points at the receiving endpoint rather than MK.IO.

Delete a rule

curl -X DELETE "https://app.mk.io/api/v1/projects/<PROJECT_NAME>/webhook/rules/job-notifications" \

-H "Authorization: Bearer <YOUR_TOKEN>"

Deleting a rule also removes its event history, so export anything you need first.

What goes wrong

• A PUT drops fields you forgot to include. It replaces the entire spec. Read the rule, change what you need, and send the complete spec back.
• Secrets look wrong on read. Authentication values are write-only and read back masked. That is expected; they are still sent on delivery.
• Events never arrive. Check the /events history. A Failed status means your endpoint rejected the delivery, so verify it is reachable over HTTPS and returns a success response. See the handler guidance in Webhooks.

What comes next

• Webhooks: the payload model, supported events, and handler design.
• Transforms and jobs: pair job workflows with completion events.