# Webhooks

Webhook endpoints for receiving events

## Get Multi-Webhook Configuration

> Retrieves all configured additional webhooks including their names, URLs, and custom headers.

```json
{"openapi":"3.1.0","info":{"title":"Messaging API","version":"1.38.1"},"tags":[{"name":"Webhooks","description":"Webhook endpoints for receiving events"}],"servers":[{"description":"Production server","url":"https://waba-v2.360dialog.io"}],"security":[{"D360-API-KEY":[]}],"components":{"securitySchemes":{"D360-API-KEY":{"description":"API Key for Messaging API authentication. Send your API key in the D360-API-KEY header.","in":"header","name":"D360-API-KEY","type":"apiKey"}},"schemas":{"multi_webhook.GetAllMultiWebhooksResp":{"description":"Response containing the multi-webhook enabled state and all configured destinations","properties":{"destinations":{"items":{"$ref":"#/components/schemas/config.Destination"},"type":"array","uniqueItems":false},"enabled":{"type":"boolean"}},"type":"object"},"config.Destination":{"properties":{"headers":{"additionalProperties":{"type":"string"},"type":"object"},"name":{"type":"string"},"url":{"type":"string"}},"required":["name","url"],"type":"object"},"utils.ErrorResp":{"properties":{"error":{"type":"string"}},"type":"object"},"utils.SuccessResp":{"properties":{"message":{"type":"string"}},"type":"object"}}},"paths":{"/multi_webhook":{"get":{"description":"Retrieves all configured additional webhooks including their names, URLs, and custom headers.","operationId":"get-multi-webhook-config","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/multi_webhook.GetAllMultiWebhooksResp"}}},"description":"Multi-webhook configuration retrieved successfully"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/utils.ErrorResp"}}},"description":"Unauthorized - Invalid or missing D360-API-KEY"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/utils.SuccessResp"}}},"description":"Multi webhook is disabled - use POST to enable it first"}},"summary":"Get Multi-Webhook Configuration","tags":["Webhooks"]}}}}
```

## Enable/Disable Multi-Webhook

> Enable or disable the multi-webhook feature. When enabling, you can optionally provide initial destinations. If already enabled, use PUT to add more destinations. Destination names must be unique.

```json
{"openapi":"3.1.0","info":{"title":"Messaging API","version":"1.38.1"},"tags":[{"name":"Webhooks","description":"Webhook endpoints for receiving events"}],"servers":[{"description":"Production server","url":"https://waba-v2.360dialog.io"}],"security":[{"D360-API-KEY":[]}],"components":{"securitySchemes":{"D360-API-KEY":{"description":"API Key for Messaging API authentication. Send your API key in the D360-API-KEY header.","in":"header","name":"D360-API-KEY","type":"apiKey"}},"schemas":{"multi_webhook.PostMultiWebhooksReq":{"description":"Request payload to enable or disable the multi-webhook feature. Set enabled=true with optional destinations to enable, or enabled=false to disable.","properties":{"destinations":{"items":{"$ref":"#/components/schemas/config.Destination"},"type":"array","uniqueItems":false},"enabled":{"type":"boolean"}},"required":["enabled"],"type":"object"},"config.Destination":{"properties":{"headers":{"additionalProperties":{"type":"string"},"type":"object"},"name":{"type":"string"},"url":{"type":"string"}},"required":["name","url"],"type":"object"},"utils.SuccessResp":{"properties":{"message":{"type":"string"}},"type":"object"},"utils.ErrorResp":{"properties":{"error":{"type":"string"}},"type":"object"}}},"paths":{"/multi_webhook":{"post":{"description":"Enable or disable the multi-webhook feature. When enabling, you can optionally provide initial destinations. If already enabled, use PUT to add more destinations. Destination names must be unique.","operationId":"enable-multi-webhook","requestBody":{"content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"$ref":"#/components/schemas/multi_webhook.PostMultiWebhooksReq","summary":"requestBody","description":"Multi-webhook configuration"}]}}},"description":"Multi-webhook configuration","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/utils.SuccessResp"}}},"description":"Operation started successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/utils.ErrorResp"}}},"description":"Bad request - already enabled, duplicate destination names, or max destinations exceeded"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/utils.ErrorResp"}}},"description":"Unauthorized - Invalid or missing D360-API-KEY"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/utils.ErrorResp"}}},"description":"Internal server error"}},"summary":"Enable/Disable Multi-Webhook","tags":["Webhooks"]}}}}
```

## Append Webhook Destinations

> Append additional destinations to the existing multi-webhook configuration. Multi-webhook must be enabled first via POST. Destination names must be unique and not conflict with existing ones. Total destinations cannot exceed the configured maximum.

```json
{"openapi":"3.1.0","info":{"title":"Messaging API","version":"1.38.1"},"tags":[{"name":"Webhooks","description":"Webhook endpoints for receiving events"}],"servers":[{"description":"Production server","url":"https://waba-v2.360dialog.io"}],"security":[{"D360-API-KEY":[]}],"components":{"securitySchemes":{"D360-API-KEY":{"description":"API Key for Messaging API authentication. Send your API key in the D360-API-KEY header.","in":"header","name":"D360-API-KEY","type":"apiKey"}},"schemas":{"multi_webhook.PutMultiWebhooksReq":{"description":"Request payload to append additional webhook destinations. Destination names must not conflict with existing ones.","properties":{"destinations":{"items":{"$ref":"#/components/schemas/config.Destination"},"type":"array","uniqueItems":false}},"required":["destinations"],"type":"object"},"config.Destination":{"properties":{"headers":{"additionalProperties":{"type":"string"},"type":"object"},"name":{"type":"string"},"url":{"type":"string"}},"required":["name","url"],"type":"object"},"utils.SuccessResp":{"properties":{"message":{"type":"string"}},"type":"object"},"utils.ErrorResp":{"properties":{"error":{"type":"string"}},"type":"object"}}},"paths":{"/multi_webhook":{"put":{"description":"Append additional destinations to the existing multi-webhook configuration. Multi-webhook must be enabled first via POST. Destination names must be unique and not conflict with existing ones. Total destinations cannot exceed the configured maximum.","operationId":"add-multi-webhook-destinations","requestBody":{"content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"$ref":"#/components/schemas/multi_webhook.PutMultiWebhooksReq","summary":"requestBody","description":"Destinations to append"}]}}},"description":"Destinations to append","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/utils.SuccessResp"}}},"description":"Operation started successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/utils.ErrorResp"}}},"description":"Bad request - duplicate destination name or max destinations exceeded"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/utils.ErrorResp"}}},"description":"Unauthorized - Invalid or missing D360-API-KEY"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/utils.SuccessResp"}}},"description":"Multi webhook is disabled - use POST to enable it first"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/utils.ErrorResp"}}},"description":"Internal server error"}},"summary":"Append Webhook Destinations","tags":["Webhooks"]}}}}
```

## Update a Webhook Destination

> Updates specific properties (url, headers) of an existing webhook destination identified by name. Multi-webhook must be enabled first via POST.

```json
{"openapi":"3.1.0","info":{"title":"Messaging API","version":"1.38.1"},"tags":[{"name":"Webhooks","description":"Webhook endpoints for receiving events"}],"servers":[{"description":"Production server","url":"https://waba-v2.360dialog.io"}],"security":[{"D360-API-KEY":[]}],"components":{"securitySchemes":{"D360-API-KEY":{"description":"API Key for Messaging API authentication. Send your API key in the D360-API-KEY header.","in":"header","name":"D360-API-KEY","type":"apiKey"}},"schemas":{"config.Destination":{"properties":{"headers":{"additionalProperties":{"type":"string"},"type":"object"},"name":{"type":"string"},"url":{"type":"string"}},"required":["name","url"],"type":"object"},"utils.SuccessResp":{"properties":{"message":{"type":"string"}},"type":"object"},"utils.ErrorResp":{"properties":{"error":{"type":"string"}},"type":"object"},"multi_webhook.GetAllMultiWebhooksResp":{"description":"Response containing the multi-webhook enabled state and all configured destinations","properties":{"destinations":{"items":{"$ref":"#/components/schemas/config.Destination"},"type":"array","uniqueItems":false},"enabled":{"type":"boolean"}},"type":"object"}}},"paths":{"/multi_webhook":{"patch":{"description":"Updates specific properties (url, headers) of an existing webhook destination identified by name. Multi-webhook must be enabled first via POST.","operationId":"update-multi-webhook-destination","requestBody":{"content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"$ref":"#/components/schemas/config.Destination","summary":"requestBody","description":"Destination with name (to identify) and updated url/headers"}]}}},"description":"Destination with name (to identify) and updated url/headers","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/utils.SuccessResp"}}},"description":"Operation started successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/utils.ErrorResp"}}},"description":"Bad request - invalid payload"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/utils.ErrorResp"}}},"description":"Unauthorized - Invalid or missing D360-API-KEY"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/utils.ErrorResp"}}},"description":"Destination not found - no destination with the given name"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/multi_webhook.GetAllMultiWebhooksResp"}}},"description":"Multi webhook is disabled"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/utils.ErrorResp"}}},"description":"Internal server error"}},"summary":"Update a Webhook Destination","tags":["Webhooks"]}}}}
```

## Delete a Webhook Destination

> Deletes a specific webhook destination from the multi-webhook configuration by its name. Multi-webhook must be enabled first via POST.

```json
{"openapi":"3.1.0","info":{"title":"Messaging API","version":"1.38.1"},"tags":[{"name":"Webhooks","description":"Webhook endpoints for receiving events"}],"servers":[{"description":"Production server","url":"https://waba-v2.360dialog.io"}],"security":[{"D360-API-KEY":[]}],"components":{"securitySchemes":{"D360-API-KEY":{"description":"API Key for Messaging API authentication. Send your API key in the D360-API-KEY header.","in":"header","name":"D360-API-KEY","type":"apiKey"}},"schemas":{"utils.SuccessResp":{"properties":{"message":{"type":"string"}},"type":"object"},"utils.ErrorResp":{"properties":{"error":{"type":"string"}},"type":"object"}}},"paths":{"/multi_webhook/{dest_name}":{"delete":{"description":"Deletes a specific webhook destination from the multi-webhook configuration by its name. Multi-webhook must be enabled first via POST.","operationId":"delete-multi-webhook-destination","parameters":[{"description":"Name of the webhook destination to delete","in":"path","name":"dest_name","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/utils.SuccessResp"}}},"description":"Destination deleted successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/utils.ErrorResp"}}},"description":"Bad request - dest_name is required"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/utils.ErrorResp"}}},"description":"Unauthorized - Invalid or missing D360-API-KEY"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/utils.ErrorResp"}}},"description":"Destination not found - no destination with the given name"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/utils.SuccessResp"}}},"description":"Multi webhook is disabled - use POST to enable it first"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/utils.ErrorResp"}}},"description":"Internal server error"}},"summary":"Delete a Webhook Destination","tags":["Webhooks"]}}}}
```

## Get Customer Webhook Configuration

> Retrieve customer webhook configuration. More info on webhook configuration can be found in our documentation: <https://docs.360dialog.com/docs/waba-messaging/webhook#get-webhook-url>.

```json
{"openapi":"3.1.0","info":{"title":"Messaging API","version":"1.38.1"},"tags":[{"name":"Webhooks","description":"Webhook endpoints for receiving events"}],"servers":[{"description":"Production server","url":"https://waba-v2.360dialog.io"}],"security":[{"D360-API-KEY":[]}],"components":{"securitySchemes":{"D360-API-KEY":{"description":"API Key for Messaging API authentication. Send your API key in the D360-API-KEY header.","in":"header","name":"D360-API-KEY","type":"apiKey"}},"schemas":{"webhook_management.WebhookConfigSchema":{"properties":{"headers":{"additionalProperties":{"type":"string"},"type":"object"},"url":{"type":"string"}},"type":"object"},"utils.ErrorResp":{"properties":{"error":{"type":"string"}},"type":"object"}}},"paths":{"/v1/configs/webhook":{"get":{"description":"Retrieve customer webhook configuration. More info on webhook configuration can be found in our documentation: https://docs.360dialog.com/docs/waba-messaging/webhook#get-webhook-url.","operationId":"get-customer-webhook-config","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/webhook_management.WebhookConfigSchema"}}},"description":"Webhook configuration retrieved successfully"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/utils.ErrorResp"}}},"description":"Unauthorized"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/utils.ErrorResp"}}},"description":"Internal server error"}},"summary":"Get Customer Webhook Configuration","tags":["Webhooks"]}}}}
```

## Set Customer Webhook Configuration

> Configure customer webhook settings. More info on webhook configuration can be found in our documentation: <https://docs.360dialog.com/docs/waba-messaging/webhook#via-api>.

```json
{"openapi":"3.1.0","info":{"title":"Messaging API","version":"1.38.1"},"tags":[{"name":"Webhooks","description":"Webhook endpoints for receiving events"}],"servers":[{"description":"Production server","url":"https://waba-v2.360dialog.io"}],"security":[{"D360-API-KEY":[]}],"components":{"securitySchemes":{"D360-API-KEY":{"description":"API Key for Messaging API authentication. Send your API key in the D360-API-KEY header.","in":"header","name":"D360-API-KEY","type":"apiKey"}},"schemas":{"webhook_management.WebhookConfigSchema":{"properties":{"headers":{"additionalProperties":{"type":"string"},"type":"object"},"url":{"type":"string"}},"type":"object"},"utils.ErrorResp":{"properties":{"error":{"type":"string"}},"type":"object"}}},"paths":{"/v1/configs/webhook":{"post":{"description":"Configure customer webhook settings. More info on webhook configuration can be found in our documentation: https://docs.360dialog.com/docs/waba-messaging/webhook#via-api.","operationId":"set-customer-webhook-config","requestBody":{"content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"$ref":"#/components/schemas/webhook_management.WebhookConfigSchema","summary":"requestBody","description":"Webhook configuration payload"}]}}},"description":"Webhook configuration payload","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/webhook_management.WebhookConfigSchema"}}},"description":"Webhook configuration updated successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/utils.ErrorResp"}}},"description":"Bad request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/utils.ErrorResp"}}},"description":"Unauthorized"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/utils.ErrorResp"}}},"description":"Internal server error"}},"summary":"Set Customer Webhook Configuration","tags":["Webhooks"]}}}}
```

## Get WABA Webhook Configuration

> Retrieve the current WABA-level webhook configuration including the URL, custom headers, WABA ID, and phone numbers associated with this WABA.

```json
{"openapi":"3.1.0","info":{"title":"Messaging API","version":"1.38.1"},"tags":[{"name":"Webhooks","description":"Webhook endpoints for receiving events"}],"servers":[{"description":"Production server","url":"https://waba-v2.360dialog.io"}],"security":[{"D360-API-KEY":[]}],"components":{"securitySchemes":{"D360-API-KEY":{"description":"API Key for Messaging API authentication. Send your API key in the D360-API-KEY header.","in":"header","name":"D360-API-KEY","type":"apiKey"}},"schemas":{"waba_webhook.WABAWebhookConfigSchema":{"description":"Current WABA-level webhook configuration including the URL, headers, WABA ID, and associated phone numbers","properties":{"headers":{"additionalProperties":{"type":"string"},"type":"object"},"numbers_on_this_waba":{"items":{"type":"string"},"type":"array","uniqueItems":false},"url":{"type":"string"},"waba_id":{"type":"integer"}},"type":"object"},"utils.ErrorResp":{"properties":{"error":{"type":"string"}},"type":"object"}}},"paths":{"/waba_webhook":{"get":{"description":"Retrieve the current WABA-level webhook configuration including the URL, custom headers, WABA ID, and phone numbers associated with this WABA.","operationId":"get-waba-webhook-config","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/waba_webhook.WABAWebhookConfigSchema"}}},"description":"WABA webhook configuration retrieved successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/utils.ErrorResp"}}},"description":"Bad request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/utils.ErrorResp"}}},"description":"Unauthorized - Invalid or missing D360-API-KEY"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/utils.ErrorResp"}}},"description":"Internal server error"}},"summary":"Get WABA Webhook Configuration","tags":["Webhooks"]}}}}
```

## Set WABA Webhook Configuration

> Configure WABA-level webhook URL and optional headers. When override\_all is false, configures the webhook only for Cloud API numbers missing a phone-number-level webhook. When true, the webhook applies across all Cloud API numbers within the WABA. The webhook will be set within 15-20 seconds.

```json
{"openapi":"3.1.0","info":{"title":"Messaging API","version":"1.38.1"},"tags":[{"name":"Webhooks","description":"Webhook endpoints for receiving events"}],"servers":[{"description":"Production server","url":"https://waba-v2.360dialog.io"}],"security":[{"D360-API-KEY":[]}],"components":{"securitySchemes":{"D360-API-KEY":{"description":"API Key for Messaging API authentication. Send your API key in the D360-API-KEY header.","in":"header","name":"D360-API-KEY","type":"apiKey"}},"schemas":{"waba_webhook.SetWABAWebhookRequest":{"description":"Request payload to configure a WABA-level webhook URL. When override_all is false, it only applies to Cloud API numbers without a phone-number-level webhook. When true, it overrides all numbers.","properties":{"headers":{"additionalProperties":{"type":"string"},"type":"object"},"override_all":{"type":"boolean"},"url":{"type":"string"}},"required":["url"],"type":"object"},"waba_webhook.SetWABAWebhookResponse":{"description":"Response after initiating WABA webhook configuration. The webhook will be set within 15-20 seconds.","properties":{"message":{"type":"string"}},"type":"object"},"utils.ErrorResp":{"properties":{"error":{"type":"string"}},"type":"object"}}},"paths":{"/waba_webhook":{"post":{"description":"Configure WABA-level webhook URL and optional headers. When override_all is false, configures the webhook only for Cloud API numbers missing a phone-number-level webhook. When true, the webhook applies across all Cloud API numbers within the WABA. The webhook will be set within 15-20 seconds.","operationId":"set-waba-webhook-config","requestBody":{"content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"$ref":"#/components/schemas/waba_webhook.SetWABAWebhookRequest","summary":"requestBody","description":"WABA webhook configuration payload"}]}}},"description":"WABA webhook configuration payload","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/waba_webhook.SetWABAWebhookResponse"}}},"description":"Webhook configuration initiated successfully. Change will be applied within 15-20 seconds."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/utils.ErrorResp"}}},"description":"Bad request - Invalid URL or malformed request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/utils.ErrorResp"}}},"description":"Unauthorized - Invalid or missing D360-API-KEY"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/utils.ErrorResp"}}},"description":"Internal server error"}},"summary":"Set WABA Webhook Configuration","tags":["Webhooks"]}}}}
```