Webhooks
/v1/webhooksScope: webhooks:manage.
View the brand's webhook endpoint. The signing secret is never included. Returns 404 if the brand has none.
Authorization
bearerAuth In: header
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/v1/webhooks"{ "url": "string", "event_types": [ "string" ], "enabled": true, "include_phone": true, "disabled_reason": "string", "created_at": "string", "updated_at": "string"}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}/v1/webhooksScope: webhooks:manage.
Register the HTTPS endpoint for signed webhook events and get its signing secret, shown only once here. A brand has one endpoint: if it already has one this returns 409 conflict. The URL must be HTTPS to a public host.
Authorization
bearerAuth In: header
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/v1/webhooks" \ -H "Content-Type: application/json" \ -d '{ "url": "http://example.com", "event_types": [ "message.received" ] }'{ "url": "string", "event_types": [ "string" ], "enabled": true, "include_phone": true, "disabled_reason": "string", "created_at": "string", "updated_at": "string", "secret": "string"}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}/v1/webhooksScope: webhooks:manage.
Change the webhook endpoint: its URL, subscribed event types, enabled state, or whether its payloads include the customer phone number. Turning the phone number on, or changing the URL of an endpoint that includes it, needs the contacts:read-phone permission.
Authorization
bearerAuth In: header
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X PATCH "https://example.com/v1/webhooks" \ -H "Content-Type: application/json" \ -d '{}'{ "url": "string", "event_types": [ "string" ], "enabled": true, "include_phone": true, "disabled_reason": "string", "created_at": "string", "updated_at": "string"}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}/v1/webhooksScope: webhooks:manage.
Delete the brand's webhook endpoint and stop its deliveries. Returns 404 if the brand has none.
Authorization
bearerAuth In: header
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X DELETE "https://example.com/v1/webhooks"{ "deleted": true}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}/v1/webhooks/rotate-secretScope: webhooks:manage.
Rotate the endpoint signing secret and get the new secret, shown only once here. The previous secret keeps verifying for 24 hours so you can roll without missing a delivery.
Authorization
bearerAuth In: header
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/v1/webhooks/rotate-secret"{ "secret": "string"}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}/v1/webhooks/testScope: webhooks:manage.
Send a signed webhook.test event to the endpoint through the normal delivery path, so you can verify your signature check and connectivity. The endpoint must be enabled.
Authorization
bearerAuth In: header
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/v1/webhooks/test"{ "event_id": "string", "status": "queued"}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}