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#
Storyteller can send an agreed key in the X-Api-Key header. When a key is
configured for your account, Story and Clip notifications both include it. One
key applies to all of the account's notifications. 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.
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 | Up to three retries after the first attempt. | Up to three retries after the first attempt. |
| Retry delays | 30, 120, and 600 seconds after successive failures. Actual execution can be later. | 30, 120, and 600 seconds after successive failures. Actual execution can be later. |
| Payload on another attempt | Current state, including on retry. If the Story is no longer Published, a Published or Updated retry sends nothing. |
Current state, including on retry. |
Story and 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 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. Story and Clip delivery then follow the same bounded retry policy; neither manufactures 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.
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.