Skip to main content

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.

In general, the difference between our normal APIs and webhooks is that:

  • Requests to our API are “request-driven” (i.e. your system asks Uniform to send the latest composition for the “about us” page).
  • Webhooks are “event-driven” (i.e. new changes were made to the “about us” page, and Uniform immediately sends a webhook to inform your server).

Use cases for webhooks

The most common use-case for webhooks would be when integrating Uniform with your website hosting provider in order to trigger site rebuilds. Instead of needing to check whether or not content has changed within your project, you can follow some of the steps outlined below to have Uniform trigger this process automatically when a piece of content changes or is re-published.

Some other uses for webhooks could include;

  • Knowing when the Uniform Manifest has been regenerated (published).
  • Passing event information through to Slack or Teams in order to notify your internal stakeholders to changes in content or site rebuilds.
  • Running a test suite on a CI service when new content is published.
  • Re-building a search index when content is updated, for integrations such as Algolia.

Supported events

Uniform supports events for critical elements such as compositions and manifests. To learn more about these events and their payloads, checkout our event catalog.

Adding a Webhook

In order 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;

webhooks-adding-a-webhook
Svix Play

If you don't have a URL or your service isn't quite ready to start receiving events just yet, press the use Svix Play button to have a unique URL 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.

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.

Testing events

You can test your endpoint configuration immediately without needing to change any content within your Uniform project by heading to the “testing” tab on the webhook settings and choosing an example event to send to your endpoint. This can be useful to quickly check if your endpoint is receiving the request correctly and to trigger events to test implementation code on your server;

webhooks-testing-events

After sending an example event, click into the messages in the table below to view the message payload, all of the message attempts, and whether it succeeded or failed.

Troubleshooting Webhooks

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.

webhooks-filtering-webhook-logs

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.

Replaying messages

You may want to replay messages if:

  • If your service has downtime
  • If your endpoint was misconfigured

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.

webhooks-replaying-messages

If you need to recover from a service outage and want to replay ll 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;

webhooks-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."

Verifying the Authenticity of Webhooks

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.