Skip to main content

Trigger a webhook event for a tenant's subscriptions

POST 
/webhooks/events

Publishes an event to every active webhook in the tenant that subscribes to the given event type. Delivery is asynchronous: a 202 means the event was accepted and handed to the delivery pipeline, not that subscribers have received it.

Event types are an open namespace. Any lowercase domain.entity.action value of 2-4 dot-separated segments is accepted. The value is not checked against a list of known events — a webhook receives the event if, and only if, it was registered for that exact string. Matching is exact and case-sensitive: a webhook registered only for facility_credential_workflow.status.changed does not receive credential_workflow.status.changed.

matchedWebhooks is not a delivery receipt. It reports how many active subscriptions matched at the moment the request was accepted. Delivery repeats the lookup, so the set can change in between. Its purpose is to surface typos: because the namespace is open, a misspelled event type is accepted and then matches nothing. matchedWebhooks: 0 is the signal — it is still a 202, because having no subscribers is a valid state. A value of -1 means the subscription lookup itself failed; the event was still published.

Tenant scoping. The event is published for the tenant in the tenant-id header, and the caller must hold webhook:trigger in that tenant. A caller cannot trigger events for a tenant it does not have access to.

Payload limits. eventData is delivered verbatim and is not schema-validated. It must serialize to no more than webhook.trigger-api.max-payload-bytes (256 KiB by default); a larger payload is rejected with 400 and nothing is published.

What subscribers receive:

{
  "eventType": "domain.entity.action",
  "timestamp": "2026-09-23T09:15:00Z",
  "data": { /* your eventData, verbatim */ }
}

with Content-Type: application/json, User-Agent: CertifyOS-Webhook-Delivery/1.0, an Idempotency-Key that is stable across retries, and any headers configured on the subscription.

Request​

Responses​

Event accepted for asynchronous delivery