Webhooks
About webhooks#
Webhooks are a great way to integrate Uniform with other services within your tech stack. In their simplest form, a webhook is an event-driven request that Uniform sends to a service or server that should be reactive to the content within your Uniform project.
Webhooks differ from Uniform APIs in how they're triggered:
| Name | Triggered by | Description |
|---|---|---|
| API | Developer, on demand | An applications sends a request to Uniform for information. |
| Webhooks | System events | When an event occurs in Uniform, Uniform passes the event data to the endpoint specified in the webhook. |
Supported events#
Uniform supports events for critical elements such as compositions and manifests. To learn more about these events and their payloads, see the event catalog.
Common tasks#
Add webhook#
To start listening to messages sent through Uniform, you will need to configure your endpoints. To add an endpoint, provide a URL that you control and a list of event types that you want to listen to.
tip
If you don't have a URL or your service isn't quite ready to start receiving events, click use Svix Play under the field EndpointURL. A unique URL will be generated for you. You'll then be able to view and inspect all incoming webhooks sent to your Svix Play URL.
When configuring your endpoint, review the Event Catalog to see the full descriptions of each endpoint as well as all the fields they send.
info
If you don't specify any event types, your endpoint will receive all events, regardless of type by default. This can be helpful for getting started and for testing, but we recommend changing this to a subset later on to avoid receiving unexpected messages.
Test events#
You can test your endpoint configuration immediately without needing to change any content within your Uniform project.
- In the endpoint settings, click Testing.
- In the field Send event, select the event you want to send.
- Click Send Example.
- Your endpoint will receive the corresponding event data.
Verify authenticity#
Because your webhook endpoint is publicly available, anyone could impersonate the Uniform platform by sending events to your endpoint.
Uniform signs every webhook and metadata with a unique key for each endpoint to identify impersonated requests. You can use this signature to verify the event's authenticity.
See the Svix documentation for how to verify the event's signature.
Troubleshooting#
Filtering logs#
If you need to track down a particular message that was sent to one of your endpoints, there are a few ways to find it.
If you know what endpoint it went to, the endpoint page has a list of all messages sent it it. You can filter this list by event type. If you know roughly when the message was sent, you can further narrow down the list using the date filter.
Replaying messages#
You may want to replay messages if:
- If your service has downtime
- If your endpoint was mis-configured
If you want to replay a single event, you can find the message from the UI and click the options menu next to any of the attempts.
If you need to recover from a service outage and want to replay all the events since a given time, you can do so from the Endpoint page. On an endpoint's details page, click Options > Recover Failed Messages.
From there, you can choose a time window to recover from.
For a more granular recovery - for example, if you know the exact timestamp that you want to recover from - you can click the options menu on any message from the endpoint page. From there, click Replay... and choose to Replay all failed messages since this time.
Tracing events#
Uniform invokes webhooks during its publishing process. Details about when the publishing process was last run and which webhooks were invoked is available in the Logs tab on the webhook configuration page.