Receiving notifications#
Your endpoint receives an HTTP POST with
Content-Type: application/json; charset=utf-8 and one JSON object in the body.
Use the body's eventType to distinguish story.changed, story.deleted,
clip.changed, and clip.deleted. Use id to identify the content. For multiple
Storyteller accounts, use your configured routes to identify the account.
For *.changed, refresh the record using the supplied metadata, accounting for
the ordering limits below. For *.deleted, remove it. The Created, Updated,
Published, and Unpublished trigger settings all produce *.changed bodies.
Authenticate requests#
For Clip webhooks, Storyteller can send an agreed key in the X-Api-Key header.
If a key is configured, require it at your receiver. Without a configured key,
the header is absent. Arrange the key exchange through an agreed secure channel;
keep it out of URLs, payload examples, and logs.
Existing Story webhook authentication depends on the account's integration. Confirm its headers separately before enforcing an authentication rule. There is no standard request-signature or HMAC header for these notifications.
Acknowledge receipt#
Return a 2xx status after you have accepted the notification. For example,
return 204 No Content if no response body is needed. Storyteller does not use
the response body.
Keep the endpoint fast. If processing takes time, store the accepted request in your own queue, return success, and process it asynchronously. Return success only after that handoff succeeds; Storyteller cannot detect a downstream failure after you have acknowledged the request.
Retries#
| Behavior | Stories | Clips |
|---|---|---|
| Successful response | Any 2xx. |
Any 2xx. |
| Automatic retries | None. | Up to three retries after the first attempt. |
| Retry delays | Not applicable. | 30, 120, and 600 seconds after successive failures. Actual execution can be later. |
| Payload on another attempt | Current state if the request is prepared again. | Current state, including on retry. |
Clip requests have a 30-second timeout per destination. A non-2xx response,
transport error, or timeout fails delivery. This
includes deletion notifications. If all attempts fail, automatic delivery stops;
contact the Storyteller team to investigate. Any operator retry of a non-delete
notification reads current metadata again.
If several Clip destinations are configured for the same event, a retry can resend to destinations that already succeeded. Even a single destination can receive duplicates if it accepts a request but Storyteller does not receive the response.
If content is deleted before a pending non-delete notification can be prepared, Storyteller cannot send that notification's metadata. Clip delivery then follows the same bounded retry policy; it does not manufacture a deletion body for the earlier event.
Keep your data in sync#
These webhooks provide best-effort change notifications. They do not guarantee that every change is delivered, delivered once, or delivered in order. A change can be saved in Storyteller without a notification reaching your service.
The payload does not include an event ID, revision number, change timestamp,
or previous values. eventType is a notification category, not a unique event
identifier. There is no historical replay feed. A content id identifies
the Story or Clip, not a unique event: do not permanently discard subsequent
notifications with the same id.
Build your receiver to:
- Handle repeated updates and deletes safely.
- Accept documented nulls and ignore additional JSON fields.
- Avoid treating arrival order as change order. An older update can arrive after a newer update or a deletion.
- Refresh current content through the appropriate Storyteller API when order matters, and reconcile periodically if you maintain a copy of the catalogue. Confirm the required API access with the Storyteller team.
Use webhooks to prompt a refresh. If every change must be recorded reliably, discuss that requirement with the Storyteller team before depending on these notifications for it.
Test before enabling#
With the Storyteller team, exercise the events your integration needs against a
test endpoint. Check the route, eventType, id, body, and agreed authentication header;
include a draft update, an availability change, and a deletion where applicable.
For Clips, test a temporary receiver failure followed by recovery to confirm
that retries are handled safely.
Verify that repeated requests do not create duplicate records and that a late update cannot incorrectly restore deleted or unavailable content in your system.