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 '{\n    "spec": {\n      "url": "https://your-endpoint.example.com/webhook",\n      "enabled": true,\n      "events": ["MediaKind.JobStarted", "MediaKind.JobFinished"],\n      "authentication": {\n        "headers": { "X-Webhook-Secret": "<SHARED_SECRET>" }\n      },\n      "headers": { "X-Source": "mkio" }\n    }\n  }'

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.