Webhooks

Manage the endpoints WhautoChat sends events to, the same webhooks you see under Integrations > Webhooks Connect in the app. Use it to register an endpoint from your own deployment scripts, pause one, or rotate its headers. For what each event means and how to set webhooks up in the app, see Webhooks.

Conventions

Webhooks belong to the account, not a workspace. Lists are plain arrays, updates use PUT with the full object, and header values are returned as you saved them, so treat responses as sensitive.

Endpoints

GET/v1/webhooksList webhook endpoints POST/v1/webhooksCreate a webhook endpoint GET/v1/webhooks/{id}Get a webhook endpoint PUT/v1/webhooks/{id}Replace a webhook endpoint's settings DEL/v1/webhooks/{id}Delete a webhook endpoint

The webhook object

Attributes

idstring

Webhook id

namestring

A label so you can recognise the endpoint, for example "CRM sync"

activeboolean

Only webhooks with active: true receive events

serverUrlstring

The URL that receives events

webhookHeadersobject[]

Headers sent with the verification request and with every event.

eventsstring[]

Subscribed events

createdAt, updatedAtstring

ISO 8601 timestamps

The webhook object
{
  "id": "Wq5rT1nBkM",
  "name": "CRM sync",
  "active": true,
  "serverUrl": "https://hooks.example.com/whautochat",
  "webhookHeaders": [
    { "key": "Content-Type", "value": "application/json" },
    { "key": "Authorization", "value": "Bearer YOUR_SHARED_SECRET" }
  ],
  "events": ["contact_created", "incoming_whatsapp_message"],
  "createdAt": "2026-10-14T09:12:40.512Z",
  "updatedAt": "2026-10-14T09:12:40.512Z"
}

Events

Put one or more of these values in events. The API stores whatever strings you send, but only these names ever fire.

Event	Fires when
`contact_created`	A contact is created.
`contact_tag_added`	A tag is added to a contact.
`contact_tag_removed`	A tag is removed from a contact.
`incoming_whatsapp_message`	A WhatsApp message is received.
`outgoing_whatsapp_message`	A WhatsApp message is sent.
`incoming_instagram_message`	An Instagram message is received.
`outgoing_instagram_message`	An Instagram message is sent.
`incoming_messenger_message`	A Messenger message is received.
`outgoing_messenger_message`	A Messenger message is sent.
`incoming_telegram_message`	A Telegram message is received.
`outgoing_telegram_message`	A Telegram message is sent.
`incoming_tiktok_message`	A TikTok message is received.
`outgoing_tiktok_message`	A TikTok message is sent.
`incoming_website_message`	A Live Chat message is received.
`outgoing_website_message`	A Live Chat message is sent.

Limits and checks

Your URL must answer a verification request. When you create a webhook, or change its serverUrl, WhautoChat immediately sends a POST to the URL with your webhookHeaders and the body {"message":"Webhook subscription request received","webhookUrl":"https://hooks.example.com/whautochat"}. Your server must reply with any 2xx status, or the request fails.
You can have up to 5 active webhooks per account. Creating a webhook (active or not) or switching an inactive one back on fails once you already have 5 active. Contact support if you need more.

List webhooks

GET/v1/webhooks

Query parameters

pageintegerdefault 1

Page number, starting at 1

limitintegerdefault 10

Results per page. Max 100; larger values are capped at 100.

200 OK: a JSON array of webhooks, newest first.

Errors

Status	Body	When
`401`	`{"message":"Unauthorized"}`	The `x-api-key` header is missing, invalid or the key was deleted
`500`	`{"error":"Could not retrieve Webhooks"}`	Something went wrong on our side. Retry, and contact support if it continues.

Request
curl "https://api.whauto.chat/v1/webhooks?page=1&limit=20" \
  -H "x-api-key: $WHAUTOCHAT_API_KEY"

Response 200
[
  {
    "id": "Wq5rT1nBkM",
    "name": "CRM sync",
    "active": true,
    "serverUrl": "https://hooks.example.com/whautochat",
    "webhookHeaders": [
      { "key": "Content-Type", "value": "application/json" },
      { "key": "Authorization", "value": "Bearer YOUR_SHARED_SECRET" }
    ],
    "events": ["contact_created", "incoming_whatsapp_message"],
    "createdAt": "2026-10-14T09:12:40.512Z",
    "updatedAt": "2026-10-14T09:12:40.512Z"
  }
]

Create a webhook

POST/v1/webhooks

Body parameters

namestringrequired

A label so you can recognise the endpoint, for example "CRM sync"

serverUrlstringrequired

The URL that receives events. Use https. It must answer the verification request with 2xx.

eventsstring[]required

At least one event

webhookHeadersobject[]required

At least one header. Sent with the verification request and with events.

activebooleanrequired

true to start receiving events now, false to save it paused. Must be a real boolean, not "true".

200 OK: the webhook object.

Errors

Status	Body	When
`400`	`{"error":"Invalid parameters"}`	A field is missing, `events` or `webhookHeaders` is empty, or `active` is not a boolean
`401`	`{"message":"Unauthorized"}`	The `x-api-key` header is missing, invalid or the key was deleted
`500`	`{"error":"Could not create Webhook"}`	Your URL did not reply `2xx` to the verification request, you already have 5 active webhooks, or something went wrong on our side. Check your URL and webhook count, then retry.

Request
curl -X POST "https://api.whauto.chat/v1/webhooks" \
  -H "x-api-key: $WHAUTOCHAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CRM sync",
    "serverUrl": "https://hooks.example.com/whautochat",
    "events": ["contact_created", "incoming_whatsapp_message"],
    "webhookHeaders": [
      { "key": "Content-Type", "value": "application/json" },
      { "key": "Authorization", "value": "Bearer YOUR_SHARED_SECRET" }
    ],
    "active": true
  }'

Response 200
{
  "id": "Wq5rT1nBkM",
  "name": "CRM sync",
  "active": true,
  "serverUrl": "https://hooks.example.com/whautochat",
  "webhookHeaders": [
    { "key": "Content-Type", "value": "application/json" },
    { "key": "Authorization", "value": "Bearer YOUR_SHARED_SECRET" }
  ],
  "events": ["contact_created", "incoming_whatsapp_message"],
  "createdAt": "2026-10-14T09:12:40.512Z",
  "updatedAt": "2026-10-14T09:12:40.512Z"
}

Get a webhook

GET/v1/webhooks/{id}

Path parameters

idstringrequired

Webhook id

200 OK: the webhook object.

Errors

Status	Body	When
`401`	`{"message":"Unauthorized"}`	The `x-api-key` header is missing, invalid or the key was deleted
`404`	`{"error":"Webhook not found"}`	No webhook with that id in your account
`500`	`{"error":"Could not retrieve Webhook"}`	Something went wrong on our side. Retry, and contact support if it continues.

Request
curl "https://api.whauto.chat/v1/webhooks/Wq5rT1nBkM" \
  -H "x-api-key: $WHAUTOCHAT_API_KEY"

Response 200
{
  "id": "Wq5rT1nBkM",
  "name": "CRM sync",
  "active": true,
  "serverUrl": "https://hooks.example.com/whautochat",
  "webhookHeaders": [
    { "key": "Content-Type", "value": "application/json" },
    { "key": "Authorization", "value": "Bearer YOUR_SHARED_SECRET" }
  ],
  "events": ["contact_created", "incoming_whatsapp_message"],
  "createdAt": "2026-10-14T09:12:40.512Z",
  "updatedAt": "2026-10-14T09:12:40.512Z"
}

Update a webhook

PUT/v1/webhooks/{id}

Replaces the webhook's settings. Send all five body fields from Create a webhook every time, including the ones you are not changing; a partial body returns 400. The verification request is sent again only if serverUrl changes.

To pause a webhook, send its current settings with "active": false.

Path parameters

idstringrequired

Webhook id

200 OK: the updated webhook object.

Errors

Status	Body	When
`400`	`{"error":"Invalid parameters"}`	A field is missing, `events` or `webhookHeaders` is empty, or `active` is not a boolean
`401`	`{"message":"Unauthorized"}`	The `x-api-key` header is missing, invalid or the key was deleted
`404`	`{"error":"Webhook not found"}`	No webhook with that id in your account
`500`	`{"error":"Could not create Webhook"}`	Your new URL did not reply `2xx` to the verification request, switching the webhook back on would exceed 5 active webhooks, or something went wrong on our side. Check your URL and webhook count, then retry.

Request
curl -X PUT "https://api.whauto.chat/v1/webhooks/Wq5rT1nBkM" \
  -H "x-api-key: $WHAUTOCHAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CRM sync",
    "serverUrl": "https://hooks.example.com/whautochat",
    "events": ["contact_created", "contact_tag_added", "incoming_whatsapp_message"],
    "webhookHeaders": [
      { "key": "Content-Type", "value": "application/json" },
      { "key": "Authorization", "value": "Bearer YOUR_NEW_SECRET" }
    ],
    "active": true
  }'

Response 200
{
  "id": "Wq5rT1nBkM",
  "name": "CRM sync",
  "active": true,
  "serverUrl": "https://hooks.example.com/whautochat",
  "webhookHeaders": [
    { "key": "Content-Type", "value": "application/json" },
    { "key": "Authorization", "value": "Bearer YOUR_NEW_SECRET" }
  ],
  "events": ["contact_created", "contact_tag_added", "incoming_whatsapp_message"],
  "createdAt": "2026-10-14T09:12:40.512Z",
  "updatedAt": "2026-10-14T10:05:18.093Z"
}

Delete a webhook

DEL/v1/webhooks/{id}

Deletes the endpoint. It stops receiving events immediately.

Path parameters

idstringrequired

Webhook id

200 OK: { "success": true }.

Errors

Status	Body	When
`401`	`{"message":"Unauthorized"}`	The `x-api-key` header is missing, invalid or the key was deleted
`404`	`{"error":"Webhook not found"}`	No webhook with that id in your account
`500`	`{"error":"Could not delete Webhook"}`	Something went wrong on our side. Retry, and contact support if it continues.

Request
curl -X DELETE "https://api.whauto.chat/v1/webhooks/Wq5rT1nBkM" \
  -H "x-api-key: $WHAUTOCHAT_API_KEY"

Response 200
{ "success": true }

The webhook object​

Events​

Limits and checks​

List webhooks​

Create a webhook​

Get a webhook​

Update a webhook​

Delete a webhook​

The webhook object

Events

Limits and checks

List webhooks

Create a webhook

Get a webhook

Update a webhook

Delete a webhook