Managing webhooks

Before you begin

Make sure you've read Webhooks overview and Get started with webhooks before starting to create and manage your webhooks. Those articles contain details about how the webhooks work and how to use them.

List available event types and payload details

This section explains how to list the available webhooks and their payload details.

List available event types with the API

The List of webhook event types endpoint returns information about the available event types and examples of their payloads. You can retrieve them by sending a GET request to the endpoint.

Here's an example of the webhook event type information returned by the endpoint:

    {
      "id": "c7d1be74-efd9-4555-b3f0-80ae9031963f",
      "module_name": "verifications",
      "module_label": "Verifications",
      "name": "bgcheck.result.available",
      "description": "Triggered when background check result is available",
      "payload_example": {
        "data": {
          "meta": {
            "event_type": "bgcheck.result.available",
            "event_type_id": "af7ce5be-d404-4788-aed5-9a5fce1b66c8",
            "organization_id": "987deccd-cef2-4c0f-a068-7cb07971bcfe",
            "organization_name": "Deel",
            "tracking_id": "q8tVRj_Je00wJLY2GriqT10nUjBZ"
          },
          "resource": {
            "candidate_email": "[email protected]",
            "completed_at": "2024-09-05T08:32:51. 658Z",
            "contract_id": "3072cm7",
            "created_at": "2024-09-05T08:28:24.394Z",
            "id": "d1f5e39c-fcfd-4f08-b5fa-66ce7112ffef",
            "is_complete": true,
            "name": "Softcheck",
            "package": null,
            "result": "CLEARED",
            "status": "COMPLETE",
            "third party_name": "request softcheck"
          }
        },
        "timestamp": "2024-09-05T08:32:52. 119Z"
      },
      "created_at": "2024-08-28T10:51:50.868Z",
      "updated_at": "2024-08-28T10:51:50.868Z"
    }

List available event types in the UI

The list of available event types is also available from the Developer Center in the UI. To see the available event types:

1. Go to More > Developer and go to the Webhooks tab.
2. Click Event payload.

3. Browse the available payloads in the resulting screen.

Subscribe to a webhook

You can register your endpoint via the API or directly in the Developer Center. This section explains how to do that.

Subscribe to a webhook with the API

You can use the dedicated Create a webhook endpoint to subscribe to a webhook. Following is an example of the request, for more information, refer to the API reference.

curl --request POST \
     --url https://api-sandbox.demo.deel.com/rest/v2/webhooks \
     --header 'accept: application/json' \
     --header 'authorization: Bearer {token}' \
     --header 'content-type: application/json' \
     --data '
{
  "status": "enabled",
  "api_version": "v2",
  "name": "Demo webhook",
  "description": "My webhook description",
  "url": "https://webhook.site/d3m0d3m0-d3m0-d3m0-d3m0-d3m0d3m0d3m0",
  "events": [
    "contract.created"
  ]
}
'

Subscribe to a webhook in the UI

To subscribe to a webhook in the UI:

1. Go to More > Developer and go to the Webhooks tab.

2. Click Add webhook.

   

3. Enter the webhook details, then click Continue.

   

4. Select the events you want to subscribe to, then click Continue.

5. Review your settings and click Finalize Webhook.

   

Disabling webhook subscriptions

You can disable an existing webhook from both the API and UI.

Disable a webhook subscription with the API

To disable a webhook subscription, use the dedicated Edit a webhook endpoint and set the status parameter to disabled. For more information, refer to the API reference.

Disable a webhook subscription in the UI

To disable a webhook subscription in the UI:

1. Go to More > Developer and go to the Webhooks tab.
2. Locate the webhook you want to disable, click the ellipsis (three dots), then select Disable.

Delete webhook subscriptions

When you no longer need a webhook subscription, or if you need to change aspects of the subscription that cannot be edited, such as the URL, you may delete the subscription. You can do so from the API or the UI.

Before deleting a webhook, consider that events will no longer be notified to your endpoint after the webhook is deleted.

Delete a webhook subscription with the API

To delete a webhook subscription, use the dedicated Delete a webhook endpoint. For more information, refer to the API reference.

Delete a webhook subscription in the UI

To delete a webhook subscription in the UI:

1. Go to More > Developer and go to the Webhooks tab.

2. Locate the webhook you want to delete, click the ellipsis (three dots), then select Delete.

   

3. On the confirmation dialog, click Delete.