> ## Documentation Index
> Fetch the complete documentation index at: https://dub.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> Use webhooks to get real-time notifications on events happening across your Dub workspace.

> [!NOTE]
>
> Webhooks are available on the [Business plan](https://dub.co/pricing) and
> above.

Webhooks allows you to listen to real-time events happening across your Dub workspace. With webhooks, you can build custom integrations with Dub, such as:

* Triggering a Zap on [Zapier](https://dub.co/integrations/zapier) when a new link is created in Dub
* Sending click events in real-time to [Segment](https://dub.co/integrations/segment) for further processing
* Get a [Slack](https://dub.co/integrations/slack) notification when someone clicks on your pitch deck link
* Building gamified referral programs – e.g. increment usage credits for the referrer when a [new signup](/docs/conversions/leads) happens

> [!WARNING]
>
> The following actions do not trigger `link.*` webhook events:
>
> * [Bulk create links](/docs/api-reference/links/bulk-create), [Bulk update links](/docs/api-reference/links/bulk-update), and [Bulk delete links](/docs/api-reference/links/bulk-delete)
> * Creating a link with [Upsert a link](/docs/api-reference/links/upsert) (updating an existing link with it does trigger `link.updated`)
> * Links created, updated, or deleted by partners from the partner portal
> * Links created via imports or the Slack `/shorten` command
> * Links deleted as a result of deleting a domain or workspace

In this guide, we'll show you how to configure webhooks for your Dub workspace and a list of available events you can listen to.

## Creating a webhook

To create a webhook for your Dub workspace, you'll need to follow these steps:

Navigate to the [**Webhooks** settings page](https://app.dub.co/webhooks) in your Dub workspace.

![Create Webhook](https://mintcdn.com/dub/Cq_ZR-h4cvDWUQ49/images/create-webhook.png?fit=max\&auto=format\&n=Cq_ZR-h4cvDWUQ49\&q=85\&s=dfd19bd36edd09d7b92f289018310d2b)

Click on **Create webhook** to create a new webhook.

![Create Webhook Form](https://mintcdn.com/dub/Cq_ZR-h4cvDWUQ49/images/create-webhook-form.png?fit=max\&auto=format\&n=Cq_ZR-h4cvDWUQ49\&q=85\&s=c475fb065b000ea36f97ce950ca49ed4)

Fill in the required fields in the webhook creation form:

1. **Name**: Give your webhook a name that helps you identify it.
2. **URL**: Enter the URL of the endpoint where you want to send the webhook. We recommend using [webhook.site](https://webhook.site/) to test your webhook.
3. **Webhook events**: Select the events you want to listen to. You can select multiple events. Refer to the [Event Types](/docs/webhooks/event-types) section to see the list of available events.

> [!NOTE]
>
> Partner events (e.g. `partner.enrolled`, `commission.created`) are only listed
> if your workspace has a [Dub Partners](https://dub.co/partners) program.

If you select `link.clicked`, you can also choose which links trigger the event:

* **All links**: Trigger the webhook for every link in your workspace.
* **Include specific folders** (recommended): Trigger the webhook for all links in the folders you select.
* **Include specific links**: Trigger the webhook only for the links you select.

Finally, click on **Create webhook** to create the webhook.

Once the webhook is created, Dub generates a **signing secret** for it, which you can find in the webhook's **Configuration** tab. Use it to verify that incoming requests came from Dub. Learn more about [verifying webhook requests](/docs/webhooks/verify-webhook-requests).

## Viewing webhook event logs

We also provide you with a webhook event logs page where you can view all the webhook events that have been sent to your webhook endpoint in real-time.

To view the webhook event logs, select the webhook from the [**Webhooks** settings page](https://app.dub.co/webhooks) and click on the **Event Logs** tab.

Here, you'll see a list of all the webhook events that have been sent to your webhook endpoint:

![Webhook Event Logs](https://mintcdn.com/dub/Ov88iRdrq0bwy1U-/images/webhook-event-logs.png?fit=max\&auto=format\&n=Ov88iRdrq0bwy1U-\&q=85\&s=ee9bd0d34ea6e20049e26d3a856c55dc)

You can also select on a specific event, which will open up a sheet with more details about the event:

![Webhook Event Logs Details](https://mintcdn.com/dub/Ov88iRdrq0bwy1U-/images/webhook-event-logs-details.png?fit=max\&auto=format\&n=Ov88iRdrq0bwy1U-\&q=85\&s=957ffe2c254fe4abf1f270070d57d9a2)

## Sending test events

You can send test events to your webhook URL to ensure that it's working correctly. To do this:

**1. Go to the webhook details page**

Navigate to the [**Webhooks** settings page](https://app.dub.co/webhooks) and select the webhook you want to test.

Click on the **Configuration** tab to open the webhook details page.

**2. Open the test event modal**

Select the `⋮` icon on the top right of the page, and click on **Send test event**.

![Send Test Event](https://mintcdn.com/dub/Ov88iRdrq0bwy1U-/images/send-test-event.png?fit=max\&auto=format\&n=Ov88iRdrq0bwy1U-\&q=85\&s=b67aec5fe9c66860f67d8cadb4d67885)

This will open up a modal where you can select the event you want to send.

![Send Test Event Modal](https://mintcdn.com/dub/Ov88iRdrq0bwy1U-/images/send-test-event-modal.png?fit=max\&auto=format\&n=Ov88iRdrq0bwy1U-\&q=85\&s=dd45b26b70cbecde3b6671d69d698415)

**3. Send the test event**

Select the event you want to send, and click on **Send test webhook**.

![Send Test Webhook](https://mintcdn.com/dub/Ov88iRdrq0bwy1U-/images/send-test-webhook.png?fit=max\&auto=format\&n=Ov88iRdrq0bwy1U-\&q=85\&s=6747758ca5263e1dee57953a44763f99)

You'll see a success message and receive the webhook event in the webhook endpoint you specified.

## Retry Behaviour

If your webhook endpoint does not respond with a success status code (2XX), we retry the request to ensure every message will be delivered. You can see all the retry attempts in your webhook event logs.

Webhooks are retried until they are successfully delivered – with an exponential backoff to avoid overwhelming your webhook endpoint (also known as the "[thundering herd problem](https://en.wikipedia.org/wiki/Thundering_herd_problem)"). The delay is capped at 24 hours from the 5th retry attempt onwards.

| Retry attempt | Delay |
| - | - |
| 1st | 12s |
| 2nd | 2m 28s |
| 3rd | 30m 8s |
| 4th | 6h 7m 6s |
| 5th | 24h |
| 6th | 24h |
| ... | ... |

### Temporary Disablement

If a webhook endpoint consistently fails, it will be automatically disabled after a series of failed attempts.

An email notification will be sent to a workspace owner at the following intervals:

* After 5, 10, and 15 consecutive failed attempts.
* On the 20th consecutive failed attempt, the **webhook will be disabled**.

This mechanism ensures that non-responsive endpoints do not continue to receive retry attempts indefinitely, maintaining system efficiency and preventing unnecessary load on both the sender and receiver.

To re-enable a disabled webhook, open the webhook from the [**Webhooks** settings page](https://app.dub.co/webhooks), select the `⋮` icon on the top right of the page, and click on **Enable webhook**.

## IP allowlist

If your endpoint sits behind a firewall or IP allowlist, you'll need to allow traffic from the following IP addresses – these are the IPs that Dub uses to deliver events (and retries):

```
3.125.136.186/32
18.198.95.233/32
3.69.157.89/32
3.69.220.58/32
52.58.170.183/32
3.74.98.166/32
100.51.235.36/32
3.230.190.166/32
3.232.167.47/32
34.198.105.68/32
34.199.12.224/32
18.206.116.131/32
```

> [!NOTE]
>
> This list can potentially change over time. For the most up-to-date list, fetch it directly from [api.upstash.com/v2/qstash/ipv4](https://api.upstash.com/v2/qstash/ipv4).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.