Event delivery
This is the request Narrative sends to you — the endpoint you registered as a subscription’s url. It is
described here so you can generate a handler for it; it is not something you call.
Every delivery is a POST with Content-Type: application/json and an X-Narrative-Secret header carrying the
subscription’s secret. Compare that header against the secret you stored when you created the subscription
and reject anything that does not match.
Return any 2xx. Narrative treats everything else — including a connection failure — as a failed attempt and
retries with exponential backoff until the event’s attempt budget runs out, so make your handler idempotent on
the envelope’s id.
Authorizations
Sent by Narrative on every webhook delivery, carrying the secret of the subscription the event belongs to.
Your endpoint should compare it against the secret returned when the subscription was created and reject
anything that does not match. This scheme applies only to deliveries Narrative makes to you — it is never
used on requests you make to the API.
Body
The body Narrative POSTs to a subscription's url. Every delivery has the same four-field envelope; type tells
you what data contains.
Unique per delivery attempt-group. Retries of the same event reuse this id, so use it to make your handler idempotent.
When the event was queued, RFC 3339 with a Z offset. Note this differs from the created_at on
WebhookSubscriptionResponse, which has no offset.
job.<state> for job events — job.pending, job.scheduled, job.running, job.completed,
job.pending_cancellation, job.cancelled, job.failed.
<app_name>.<event_type> for app events, where <app_name> is the app's name lowercased with a leading
"the" dropped, punctuation removed and spaces replaced by underscores — so an app named "My Test App"
reporting s3_delivery.completed produces my_test_app.s3_delivery.completed.
"job.completed"
"my_test_app.s3_delivery.completed"
JobEventData when type starts with job., otherwise the app event payload. App payloads are
app-defined, so they are not described here beyond the fields Narrative adds.
Response
Any 2xx marks the event delivered. The response body is recorded for troubleshooting but not otherwise used.