Change Notification Webhooks

Change notification webhooks let your service respond to changes to Stories and Clips in Storyteller. Use them to refresh content metadata, update a catalogue, or remove content from your own system.

Storyteller sends an HTTP POST to an endpoint you provide. Each notification contains a JSON object describing one Story or Clip. For deletion notifications, use the content's Storyteller id to identify the record to remove.

Guide	What it covers
Story events	Supported notifications, publication filtering, and Story payloads.
Clip events	Supported notifications, availability changes, and Clip payloads.
Receiving notifications	Authentication, responses, retries, and keeping your data in sync.

Set up an integration

Contact the Storyteller team to confirm availability and configure webhooks for your account. Provide:

1. The content types and events you need: Created, Updated, Published, Unpublished, or Deleted.
2. The HTTPS endpoint or endpoints that should receive those notifications.
3. Your authentication requirements and a test endpoint for validation.

You can use one endpoint for several configured events, for example:

https://example.com/webhooks/storyteller

This is an example of an endpoint you host. Each event still has its own configuration, so tell the Storyteller team which events should use that URL. Your receiver uses the body's eventType to identify the content type and whether to refresh or delete it. Separate endpoints remain an option.

If you receive notifications for multiple Storyteller accounts, use routes that also identify the account; the body does not contain an account ID.

Only configured events send requests. Ask the Storyteller team to change or disable a destination when needed. A request already in progress may still arrive after a destination is disabled.

Event types

Every notification includes one of these eventType values:

eventType	Meaning
story.changed	Refresh the Story using the supplied current metadata.
story.deleted	Remove the Story identified by id.
clip.changed	Refresh the Clip using the supplied current metadata.
clip.deleted	Remove the Clip identified by id.

Created, Updated, Published, and Unpublished are the triggers you configure. They all send the corresponding *.changed event type. Deleted sends *.deleted. The event type identifies both the content type and the receiver action; there is no separate contentType field.

Understand the notification

Except for deletion, the payload contains the content's state when Storyteller prepares the request. It does not contain the previous values, a list of changed fields, or a snapshot captured at the moment of the original change. A retry can therefore contain different values from the first attempt.

For a *.changed notification, status describes the state read when the request is prepared. For example, a Clip publication trigger can result in "eventType": "clip.changed" with "status": "Archived" if the Clip becomes unavailable before delivery. The body asks you to refresh the content; it does not claim that a particular publication transition is happening now.

Notifications are delivered asynchronously and can be delayed, duplicated, missed, or received out of order. There is no guaranteed delivery time. Read Receiving notifications before using webhooks to maintain a copy of Storyteller content.