Requirements

1. You're familiar with how webhooks work.
2. You're familiar with the webhooks best practices.
3. You have a Deel account.
4. You're authenticated with the Deel API. (only applicable when using API)

Listen for events

To receive webhooks, you first need an endpoint. Create an endpoint of your choice to receive events that are published to a webhook topic.

You can create an HTTPS endpoint on your app as a webhook receiver and specify that endpoint's URL as the webhook subscription's endpoint.

Create a webhook subscription

After setting your webhook endpoint, register the endpoint with Deel so Deel knows where to deliver events.

Create a subscription with the API

You can programmatically create a webhook subscription. You can enter any URL as the destination for events and which event types to subscribe to.

The following example creates an endpoint that notifies you when charges succeed or fail.

curl --location --request POST 'https://api.letsdeel.com/rest/v2/webhooks' \
--header 'Authorization: Bearer {token}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "name": "My webhook",
  "description": "My first webhook.",
  "events": [
    "contract.created",
  ],
  "status": "enabled",
  "url": "https://example.com/listening/for/webhook/events",
  "api_version": "v2"
  }'

Create a subscription in Developer Center

Use the following steps to register a webhook endpoint in the Developers Center.

1. Navigate to Apps & Integrations > Developer Center and go to the Webhooks tab.
2. Click on the 'Add Webhook' button.
3. Enter a name of your choice, and description (the information this Webhook will push to your application).
4. Specify the endpoint to which you would like to receive live Deel events.
5. Choose the API version.
6. On the next step, select the events you want to subscribe to.
7. Review your entries and selection. Click on Finalize Webhook to create the subscription.

Manage webhook subscriptions

You can update or delete existing webhook endpoints in the Developer Center Webhooks tab. You also have the option of disabling a webhook. Deel does not retry any notifications that are generated while the endpoint is disabled. Alternatively, you can manage webhook endpoints programmatically using Deel API.

Handle Webhook events

After you register an endpoint, Deel sends an HTTP POST request to the URL specified every time that event occurs. The HTTP POST request's parameters contain the JSON data relevant to the event that triggered the request.

Verify the webhook

Before you respond to a webhook, you can verify that the webhook was sent from Deel by calculating a digital signature.

Each webhook request includes a hex-encoded x-deel-signature header, which is generated using the app's signing key along with the data sent in the request. Learn more about verifying signatures here.

Respond to the webhook

Your application should send a 200 OK response to acknowledge that it has received data. Any response outside of the 2XX range, including 3XX HTTP redirection codes, indicates that you didn't receive the webhook.

Deel doesn't follow redirects for webhook notifications and considers them to be an error response.