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" or at a network level under network settings - webhooks as seen in this screenshot:
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 exampleProgramCreated,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 event will fail permantly and not be retried again. If ten consecutive messages fail, the webhook subscription will be disabled and any pending events for that subscription will be marked as permantly failed. An email notification will be sent to the "organization technical contact" when the webhook subscription is disabled. 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.