Dub Webhooks are currently in closed beta and would require a Business plan subscription and above. If you’d like to join the beta, reach out to us via email.

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 when a new link is created in Dub
  • Send a notification on Slack when a link is clicked
  • For building gamified referral programs with Dub Conversions – e.g. increment usage credits for both the referrer and referee when a conversion event happens

The following endpoints do not trigger webhook events: Bulk create links, Bulk update links, Bulk delete links.

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 in your Dub workspace.

Click on Create Webhook to create a new webhook.

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 to test your webhook.
  3. Signing secret: This is an auto-generated secret key that you can use to verify the authenticity of the webhook in your application.
  4. Events: Select the events you want to listen to. You can select multiple events. Refer to the Available Events section to see the list of available events.

Finally, click on Create webhook to create the webhook.

​
Available webhook events

When setting up a webhook, you can select the events you want to listen to across your Dub workspace. There are two types of events you can listen to:

  • Workspace-level events: These events are triggered in the context of your entire workspace.
  • Link-level events: These events are triggered in the context of a specific link.

​
Workspace-level events

These events are triggered in the context of your entire workspace:

Due to the high volume nature of these events, they are scoped to a specific link.

This means that you need to specify the link when creating a webhook – though you can select multiple links for the same webhook if you’d like.

​
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 and select the webhook you want to test.

Click on the Update Details 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.

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

3

Send the test event

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

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

​
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 and click on the Webhook Logs tab.

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

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

​
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”). The delay is capped at 24 hours from the 5th retry attempt onwards.

Retry attemptDelay
1st12s
2nd2m 28s
3rd30m 8s
4th6h 7m 6s
5th24h
6th24h
……

​
Signature Verification

With signature verification, you can determine if the webhook came from Dub, and has not been tampered with in transit.

All webhooks are delivered with a Dub-Signature header. Dub generates this header using a secret key that only you and Dub know.

An example header looks like this:

Dub-Signature: c9ed6a2abf93f59d761eea69908d8de00f4437b5b6d7cd8b9bf5719cbe61bf46

To verify, you can use the secret key to generate your own signature for each webhook. If both signatures match then you can be sure that a received event came from Dub.

The steps required are:

  1. Get the raw body of the request.
  2. Extract the signature from the Dub-Signature header.
  3. Calculate the HMAC of the raw body using the SHA-256 hash function and the secret.
  4. Compare the calculated HMAC with the one sent in the Dub-Signature header. If they match, the webhook is verified.

Was this page helpful?

Integrate with DubQuickstart