Webhooks

Webhooks let you push real-time events to any external endpoint. Use them to sync messages to your CRM, trigger automations in n8n/Make/Zapier, or build custom backends.

Create a Webhook Subscription

Open your Location

Go to Dashboard → Locations and select the location you want to subscribe to.

Open Settings

Click the Settings tab for that location.

Create subscription

Scroll to the Webhooks section and click Create subscription.

Fill in the form

Complete the Create subscription dialog (see fields below).

Save

Click Create subscription to save. If “Send a test ping” is enabled, a dummy event will be POSTed to your endpoint to verify it works.

Subscription Fields

Name (required)

A human-readable label so you can identify the subscription later (e.g., CRM Sync, n8n Inbound Handler).

Target URL

The HTTPS endpoint that will receive event payloads.

https://example.com/webhooks

Your endpoint must respond with a 2xx status code. Non-2xx responses are treated as failures.

Select events

Pick exactly which events should trigger a webhook. You can mix channels in a single subscription.

Inbound - a WhatsApp message is received
Outbound - a WhatsApp message is sent

iMessage

Inbound - an iMessage is received
Outbound - an iMessage is sent

SMS

Inbound - an SMS is received
Outbound - an SMS is sent

System

Message failed - a message could not be delivered (use this for retry logic or alerting)

Send a test ping after creating

When enabled, the system will POST a dummy event to your Target URL immediately after the subscription is created. Use this to confirm your endpoint is reachable and your handler parses payloads correctly.

Leave this on for the first subscription you create against a new endpoint.

The test ping body is { "type": "test.ping" }. It is not wrapped in the envelope below.

Delivery Format

Every event except the test ping is POSTed as JSON, wrapped in this envelope:

{
  "version": "1.0",
  "event": "whatsapp.inbound",
  "eventId": "3f9e2b8c-1a2d-4e3f-9b1a-2c3d4e5f6a7b",
  "timestamp": "2026-08-03T14:22:05.123Z",
  "locationId": "loc_2f9a41",
  "payload": { }
}

Field	Type	Description
`version`	`string`	Always `"1.0"`.
`event`	`string`	The event name, matching what you selected when creating the subscription.
`eventId`	`string`	Unique ID for this delivery. Use it to deduplicate retried events.
`timestamp`	`string` (ISO 8601)	When the event was dispatched.
`locationId`	`string`	The location the event belongs to.
`payload`	`object`	Event-specific data. See Event Payloads below.
`meta.traceId`	`string`	Optional. Internal trace ID, useful when reporting a delivery issue to support.

Headers

Content-Type: application/json
X-WA-Event-Id: <eventId>
X-WA-Timestamp: <unix timestamp, ms>

X-WA-Event-Id matches the eventId in the body.

Event Payloads

The payload object differs by channel and event type. message.media[].type is always one of image, video, audio, document, or unknown.

Inbound messages

whatsapp.inbound, imessage.inbound, sms.inbound - fired when a contact sends a message to one of your connected numbers.

WhatsApp
iMessage
SMS

{
  "messageId": "wamid.HBgLMTU1NTk4NzY1NDMV...",
  "locationId": "loc_2f9a41",
  "device": { "number": "15551230000", "name": "Front Desk" },
  "contact": { "id": "contact_7be31c", "name": "Jane Doe", "number": "15559876543" },
  "message": {
    "text": "Hi, is my order ready?",
    "media": [{ "url": "https://cdn.example.com/img.jpg", "type": "image" }]
  },
  "transcribedAudio": "Transcribed text from a voice note, when present"
}

{
  "messageId": "msg_9d41ab",
  "locationId": "loc_2f9a41",
  "device": { "number": "15551230000" },
  "contact": { "id": "contact_7be31c", "name": "Jane Doe", "number": "15559876543" },
  "message": { "text": "On my way, 5 min out" },
  "meta": { "transcribedAudio": "Transcribed text from a voice note, when present" }
}

{
  "messageId": "msg_4e17cd",
  "locationId": "loc_2f9a41",
  "device": { "number": "15551230000" },
  "contact": { "id": "contact_7be31c", "name": "Jane Doe", "number": "15559876543" },
  "message": { "text": "Can I reschedule to Friday?" }
}

Field	Type	Notes
`messageId`	`string`	Provider message ID.
`locationId`	`string`	The location the event belongs to.
`device.number`	`string`	The connected number that received the message.
`device.name`	`string`	Optional.
`contact.id`	`string`	GHL contact ID, if the sender is already a known contact.
`contact.name`	`string`	Optional.
`contact.number`	`string`	Sender’s number.
`message.text`	`string`	Optional. Absent for media-only messages.
`message.media`	`array`	Optional. Each item has `url` and `type`.
`transcribedAudio`	`string`	Transcript of a voice note, when transcription is enabled.
`ctwa`	`object`	WhatsApp only. Click-to-WhatsApp ad metadata, present only when the chat started from a WhatsApp ad.

transcribedAudio is top-level on WhatsApp, but nested under meta.transcribedAudio on iMessage and SMS.

Outbound messages

whatsapp.outbound, imessage.outbound, sms.outbound - fired when a message is sent from a connected number, either typed on the device or sent by the CRM.

{
  "messageId": "wamid.HBgLMTU1NTk4NzY1NDMV...",
  "source": "crm",
  "contact": { "id": "contact_7be31c", "number": "15559876543" },
  "message": { "text": "Your order is ready for pickup!" },
  "device": { "number": "15551230000", "name": "Front Desk", "instanceIndex": 0 },
  "locationId": "loc_2f9a41",
  "timestamp": "2026-08-03T14:25:10.500Z"
}

Field	Type	Notes
`messageId`	`string`
`locationId`	`string`	The location the event belongs to.
`source`	`"device"` \| `"crm"`	`device`: sent from the connected phone/app. `crm`: sent from the CRM or an automation.
`contact.id`	`string`
`contact.number`	`string`
`contact.name`	`string`	Optional. Often absent for CRM-initiated sends.
`message.text` / `message.media`		Same shape as inbound.
`device.number`	`string`	The connected number that sent it.
`device.name`	`string`	Optional.
`device.instanceIndex`	`number`	Optional. The connected instance that sent it.
`timestamp`	`string` (ISO 8601)

Message failed

message.failed - fired when an outbound message on any channel couldn’t be delivered after retries.

{
  "messageId": "msg_7c6b5a",
  "contactId": "contact_7be31c",
  "message": "Hey, following up on your appointment",
  "channelType": "whatsapp",
  "error": {
    "code": "109",
    "type": "WhatsAppFailure",
    "message": "Could not send the message. Please contact Custom Provider Support team"
  },
  "device": { "instanceIndex": 2, "phoneNumber": "15551230000" },
  "receiver": { "phoneNumber": "15559876543", "contactId": "contact_7be31c" },
  "locationId": "loc_2f9a41",
  "timestamp": "2026-08-03T14:30:00.000Z"
}

Field	Type	Notes
`messageId`	`string`
`contactId`	`string`	Optional.
`message`	`string`	Optional preview of the message body that failed to send.
`channelType`	`"whatsapp"` \| `"imessage"` \| `"sms"`	Optional.
`error.code` / `.type` / `.message`	`string`	See common codes below.
`device.instanceIndex`	`number` \| `null`
`device.phoneNumber`	`string` \| `null`	The connected number that attempted the send.
`receiver.phoneNumber`	`string`	Recipient’s number.
`receiver.contactId`	`string`	Optional.
`locationId`	`string`	The location the event belongs to.
`timestamp`	`string` (ISO 8601)	When the failure was recorded.

Common error codes:

Code	Type	Meaning
`109`	`WhatsAppFailure` / `SMSFailure` / `iMessageFailure`	The provider rejected or failed to deliver the message after retries.
`110`	`InvalidWhatsAppNumber`	The recipient’s number doesn’t have an active WhatsApp account.
`111`	`InstanceNotFound`	No connected instance matches the number the message was routed to.
`112`	`InvalidButtonFormat`	The message used an interactive button format WhatsApp rejected.

Error codes may expand over time. Key retry/alerting logic off error.type, not this list.

Best Practices

Use one subscription per integration. Keeps logs and rotation simple.
Verify with the test ping before relying on a subscription in production.
Return 2xx quickly - push slow work onto a background queue in your handler.
Be idempotent. Webhooks can occasionally be re-delivered.
Scope by channel. Don’t subscribe to events you won’t process.

Managing Subscriptions

From the Webhooks section in Location Settings you can:

View all active subscriptions, and creation date
Delete a subscription you no longer need
Create additional subscriptions for separate endpoints

Troubleshooting

Test ping never arrived

Confirm your endpoint is publicly reachable (no localhost / private IPs)
Check that it accepts POST and returns 2xx
Verify firewall/WAF rules aren’t blocking the IP

Events stopped firing

Make sure the subscription wasn’t deleted
Confirm the location still has a connected instance for the channel
Check your endpoint logs for 5xx responses (repeated failures may disable delivery)

Duplicate events

Webhooks are at-least-once. Use the top-level eventId (also sent as the X-WA-Event-Id header) to deduplicate on your side.

Home

Getting Started

WhatsApp

iMessage

SMS

Multiple Instances

Safety & Warm-Up

Features

Custom JS Features

Automation

External Integration

Data & Privacy

Create a Webhook Subscription

Subscription Fields

Name (required)

Target URL

Select events

WhatsApp

iMessage

SMS

System

Send a test ping after creating

Delivery Format

Headers

Event Payloads

Inbound messages

Outbound messages

Message failed

Best Practices

Managing Subscriptions

Troubleshooting

​Create a Webhook Subscription

​Subscription Fields

​Name (required)

​Target URL

​Select events

​WhatsApp

​iMessage

​SMS

​System

​Send a test ping after creating

​Delivery Format

​Headers

​Event Payloads

​Inbound messages

​Outbound messages

​Message failed

​Best Practices

​Managing Subscriptions

​Troubleshooting

Create a Webhook Subscription

Subscription Fields

Name (required)

Target URL

Select events

WhatsApp

iMessage

SMS

System

Send a test ping after creating

Delivery Format

Headers

Event Payloads

Inbound messages

Outbound messages

Message failed

Best Practices

Managing Subscriptions

Troubleshooting