Webhook Configuration & Management

Multiple Webhooks per Phone Number are only available for Cloud API numbers.

You can attach multiple Webhook URLs to a single phone number. This can be used to manage additional webhooks, enhancing automation and integration capabilities within your systems.

This feature allows integration options but compromises on performance. The more webhooks are attached to a number, the longer messages will take to arrive and be acknowledged, so the overall number performance will be impacted. Make sure to have this in mind when considering utilizing multiple webhooks for a single phone number. Using only one webhook is recommended for high volume accounts.

All destinations will get cloned incoming notifications from the Messaging API. But, extra webhooks will only get these notifications if the main destination (connected to the phone number) successfully receives them with 200 success code. See our documentation for Best Practices for designing Integrations.

Each phone number is limited to a maximum of 3 unique webhooks. This limit cannot be increased. You cannot attach multiple webhooks to a full WABA, only to specific phone numbers.

Webhook URLs or headers for Cloud API does not support "_"(underscore) or ":xxxx"(port)in (sub)domain names.

Invalid webhook URL: https://your_webhook.example.com Valid webhook URL: https://yourwebhook.example.com

Invalid webhook URL:https://subdomain.your_webhook.example.com:3000 Valid webhook URL: https://subdomain.yourwebhook.example.com

Enable/Disable Multiple Webhooks

POST https://waba-v2.360dialog.io/multi_webhook

Use this endpoint to enable or disable the Multiple Webhook configuration to a specific phone number.

Headers

Name	Value
Content-Type	application/json
D360-API-KEY*	API Key

Body

Name	Type	Description
enabled*	boolean	Use true to enable or false to disable this configuration.
destinations	object	Optional. Required to append new webhooks.
name	string	Name of the new webhook. *Webhook names are case-sensitive, like unique IDs.
url	string	URL of the new webhook. (www.example.com/webhook)
headers	string	"Content-Type": "application/json"

Sample Request

To enable multi-webhook feature and add new destinations.

{
  "enabled": true,
  "destinations": [
    {
      "name": "NewWebhook",
      "url": "https://newwebhook.com",
      "headers": {"Content-Type": "application/json"}
    }
  ]
}

Webhook names are case-sensitive and function like unique IDs. Therefore, a webhook named "webhook" is considered distinct from "WEBhook." The API will only add a new webhook if the <name> provided in the request does not match with any existing configuration.

To enable or disable multi-webhook feature, the destination object is not required:

{
  "enabled": true/false
}

Response

200

{
    "message": "Operation has been started, please wait several seconds until change is applied"
}

400

{
    "error": "Invalid json: <details>"
}
or

{
    "error": "Destination with name destination2 already exists"
}

or 

{
    "error": "Destination names must be unique"
}

or

{
    "error": "You cannot add more than 3 destinations"
}

500

{
    "error": "Operation failed, please retry later or contact support"
}

Get list of configured Webhooks

GET https://waba-v2.360dialog.io/multi_webhook

This endpoint retrieves all configured and additional webhooks.

Headers

Name	Value
Content-Type	application/json
D360-API-KEY*	API Key

Response

200

{
  "enabled": true,
  "destinations": [
    {
      "name": "Webhook1",
      "url": "https://example.com/webhook1",
      "headers": {"Authorization": "Bearer abc123"}
    }
      {
      "name": "Webhook2",
      "url": "https://example.com/webhook2",
      "headers": {"Authorization": "Bearer abc123"}
    }
  ]
}

419

{
    "message": "Multi webhook is disabled, use POST to enable it first"
}

Append additional Webhooks

PUT https://waba-v2.360dialog.io/multi_webhook

You can add up to 3 webhooks per phone number. This limit cannot be increased.

Headers

Name	Value
Content-Type	application/json
D360-API-KEY*	API Key

Body

Name	Type	Description
destinations*	object	Required to append new webhooks.
name*	string	Name of the new webhook. *Webhook names are case-sensitive, like unique IDs.
url*	string	URL of the new webhook. (www.example.com/webhook)
headers*	string	D360-API-KEY

Sample Request

Webhook names are case-sensitive, and function like unique IDs. Therefore, a webhook named "webhook" is considered distinct from "WEBhook." The API will only add a new webhook if the <name> provided in the request does not match with any existing configuration.

{
  "destinations": [
    {
      "name": "Webhook2",
      "url": "https://replacedwebhook2.com",
      "headers": {"Authorization": "D360-API-KEY"}
    }
  ]
}

Response

200

{
    "message": "Operation has been started, please wait several seconds until change is applied"
}

400

{
    "error": "Invalid json: <details>"
}
or

{
    "error": "Destination with name destination2 already exists"
}

or 

{
    "error": "Destination names must be unique"
}

or

{
    "error": "You cannot add more than 3 destinations"
}

500

{
    "error": "Operation failed, please retry later or contact support"
}

Update properties of an existing webhook

PATCH https://waba-v2.360dialog.io/multi_webhook

To update properties of an existing webhook, use the endpoint and specify the new webhook configuration in the request payload.

Headers

Name	Value
Content-Type	application/json
D360-API-KEY*	API Key

Body

Name	Type	Description
name*	string	Name of the existing webhook. *Webhook names are case-sensitive, like unique IDs.
url*	string	Updated URL for the existing webhook. (www.example.com/webhook)
headers*	string	D360-API-KEY

Sample Request

Webhook names are case-sensitive, and function like unique IDs. Therefore, "webhook" is considered distinct from "WEBhook". The API will only modify the webhook if the <name> passed in the request is an exact match.

{
  "name": "ExistingWebhook",
  "url": "https://updatedwebhook.com",
  "headers": {"Authorization": "D360-API-KEY"}
}

Sample Response

200

{
    "message": "Operation has been started, please wait several seconds until change is applied"
}

400

{
    "error": "Invalid json: <details>"
}
or

{
    "error": "Destination with name destination2 already exists"
}

or 

{
    "error": "Destination names must be unique"
}

500

{
    "error": "Operation failed, please retry later or contact support"
}

Delete a specific webhook configuration by name

DELETE https://waba-v2.360dialog.io/multi_webhook/{{name}}

To delete a additional webhook, use this endpoint. Remember that if you delete all webhooks, it the system will return an empty response when attempting callbacks.

Headers

Name	Value
Content-Type	application/json
D360-API-KEY*	API Key

Path Sample Request

https://waba-v2.360dialog.io/multi_webhook/Webhook2 >> Name of the webhook

Use the GET request to retrieve webhook names.

Webhook names are case-sensitive, and function like unique IDs. Therefore, a webhook named "webhook" is considered distinct from "WEBhook". The API will only delete the webhook if the <name> passed in the request is an exact match.

Response

200

{
    "message": "Operation has been started, please wait several seconds until change is applied"
}

500

{
    "error": "Operation failed, please retry later or contact support"
}