# Webhooks in Uniform

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

Source: https://docs.uniform.app/docs/guides/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 application 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**](https://www.svix.com/event-types/us/org_2HgMLYs57QWpjfM80UPmW98qTgT/).

### Webhooks and automations

Webhooks are outbound: Uniform calls a URL you host. If you want to run logic in response to a Uniform event without hosting and operating that endpoint yourself, use an [automation](https://docs.uniform.app/docs/guides/automations) instead. Automations subscribe to the same event catalog and run your code, or a set of Scout instructions, inside Uniform.

Automations can also work in the other direction. An
[incoming webhook trigger](https://docs.uniform.app/docs/guides/automations/triggers#incoming-webhooks) gives an automation a URL that external systems call to start a run, which is the reverse of the outbound webhooks described on this page.

## 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](https://www.svix.com/event-types/us/org_2HgMLYs57QWpjfM80UPmW98qTgT/)
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.

1. In the endpoint settings, click **Testing**.

   ![](https://docs.uniform.app/images/guides/webhooks/testing.png)
2. In the field **Send event**, select the event you want to send.
3. Click **Send Example**.
4. 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](https://docs.svix.com/receiving/verifying-payloads/how)
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 to 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:

- Your service has downtime
- 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.

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.