Webhooks allow your services to receive HTTP POST requests notifying you of relevant events such as when a clip is created or a program is updated.

Create and manage webhook subscriptions

You can create multiple webhook subscriptions from the "Webhooks" page of your "Organization settings". You will need to enter the URL of your receiving endpoint and choose the events you'd like to receive.

Once you have configured a subscription and enabled it, the events that you have subscribed to will start getting sent to that endpoint.
The webhook subscription page also includes details of sent events. By default, you can view the most recent 100 events, including the full request and response bodies. You can also filter this list to view recent failures or specific event types.

Technical implementation details

Webhook request body

The request body of the webhook is a JSON object with the following properties

  • Type  (string) - the type of event which caused the webhook to fire. These are structured as {entity}{change-type} , for example ProgramCreated, ClipDeleted, etc.
  • Timestamp (string) - the time when the event occured (accurate to the second)
  • ChangeId  (Guid) - A GUID representing this unique change. This ID will be common across multiple subscribers for the same event.
  • EventId  (Guid) - A GUID representing this unique event for a given subscriber.
  • Current (object) - the representation of the entity at the time the event occured. The model of current will vary based on the type of event, clip events will send a clip model, playlist events a playlist, program events a program. The models match what the management API uses for each of these entities. 

An example of a request is

{
    "Type": "ClipDeleted",
    "Timestamp": "2019-10-09T10:25:56",
    "Current": { ... }
}

Event delivery time

There may be a small delay from when actions occur to when webhook events are sent. On average it may take between 30-60 seconds for the event to be sent.

This delay will vary based on the number of webhook subscriptions active, the backlog of events to be sent, and the response time of the server(s) receiving the webhooks. 

While generally we will make a best attempt to deliver webhooks in sequence the client should handle receiving events out of order. Specifically retries may cause an old event to be sent after newer events. You can check the Timestamp  property for a record of when the event originally occurred.

Event delivery errors

Any responses with a non-successful HTTP status code (e.g. not 2XX) will be treated as an error and the event delivery will be retried. We will retry delivering the message up to 5 times with an exponential backoff up to 60 mins to deliver the event.

If an event still errors after the 5th attempt, the webhook subscription will be disabled and any pending events for that subscription are deleted. An email notification will be sent to the "organization technical contact". The subscription can be manually re-enabled if you wish to continue receiving events. Note that any events that occurred while the subscription was disabled will not be sent, even after re-enabling the subscription.

Event deduplication

While generally we attempt to de-duplicate events, it is possible we will send an event more than once.

Receivers should verify that the request is unique through X-Omny-Event-Id  HTTP header in the request. This represents the ID of the request which uniquely identifies this event and allows correlation back to the attempt to send the request. 

If you are contacting support, please include the X-Omny-Event-Id to identify the event in question.

Security

To ensure messages you receive were sent by Omny Studio, you can configure a shared secret key for your webhook subscriptions which you can verify using the X-Omny-Signature HTTP header of the request. We strongly recommend the use of this verification process to avoid any malicious actors sending to your webhook receiver endpoints.

The X-Omny-Signature HTTP header value is generated using the HMAC-SHA256 hashing function

  • Key: the shared secret value
  • Value: the body of the request (UTF-8 encoding, without any HTTP header)

Verify the generated hash encoded in hex (without leading 0x appended) matches the value provided in the X-Omny-Signature  HTTP header in your received request.

We also strongly recommend that you use an HTTPS endpoint for the webhook subscription. Events sent to a HTTPS URL will validate the TLS certificate is valid and is signed by a trusted authority.

Did this answer your question?