Webhooks

Open in the app: Webhooks (opens in a new tab)

Overview

You can use the webhooks to subscribe to some events in our system. When that related event happens in your workspace, you will get a post request on that defined webhook. Each Webhook has the following fields:

Attributes	Type	Description
`id`	`string`	The unique ID of the webhook.
`label`	`string`	The label for this webhook. May be duplicate with other labels.
`url`	`string`	The URL of the webhook.
`event`	`string`	The event that will trigger the webhook. Can be 'INCOMING_MESSAGE', 'OUTGOING_MESSAGE', 'MESSAGE_UPDATED', 'ENDING_CONV', 'NEW_CLIENT', 'NEW_CONV', 'CLIENT_UPDATED', or 'ANY_EVENT'.
`createdAt`	`string`	The timestamp when this instance was created.

In JSON Format

{
 "workspaceId": 12,
 "id": "67642054b6cc2888638e4600",
 "url": "https://yourwebsite/crm/incoming-messages....",
 "label": "Incoming message webhooks",
 "event": "INCOMING_MESSAGE ",
 "createdAt": "2024-12-19T13:32:04.009Z",
}

Webhook request payload

For conversation-related events

The payload that will be sent to the webhook URL will have the following fields:

Attributes	Type	Description
`event`	`string`	The webhook event name. Valid values: 'INCOMING_MESSAGE', 'OUTGOING_MESSAGE', 'ENDING_CONV', 'NEW_CONV'.
`workspaceId`	`number`	The workspace identifier.
`type`	`string`	The message type. Valid values: 'text', 'image', 'audio', 'document', 'video', 'location', 'interactive', 'template', 'contacts', or 'note'.
`content`	`string`	The message content.
`messageId`	`string`	The internal message identifier.
`integrationId`	`string`	The integration identifier where the message belongs. This is the integration ID of the channel where the message was sent.
`integrationType`	`string`	The integration type (channel type). Valid values: 'WHATSAPP', 'INSTAGRAM', 'TELEGRAM', 'CUSTOM'.
`externalClientId`	`string`	The external client identifier from the integration provider.
`isAgent`	`boolean`	Whether the message was sent by an agent.
`conversationId`	`string`	The conversation identifier. This is the conversation ID of the conversation where the message was sent.
`clientId`	`string`	The client identifier. This is the client ID of the client who sent the message or the client ID of the client who received the message.
`createdAt`	`string`	The message creation timestamp in ISO format.

Here is a JSON example of the payload for a conversation-related event:

{
  "event": "INCOMING_MESSAGE",
  "type": "text",
  "content": "Hello",
  "messageId": "68875c39-01b8-42a5-9273-fcfd2f697600",
  "workspaceId": 12,
  "integrationId": "6743884f784839ad14770000",
  "isAgent": false,
  "conversationId": "6728c86bf893860f458e0000",
  "clientId": "6728c77dbba874b293e60000",
  "createdAt": "Sat, 04 Jan 2025 15:35:46 GMT",
  "integrationType": "WHATSAPP",
  "externalClientId": "905301749170",
  "debug": false
}

For message status update events

The payload that will be sent to the webhook URL will have the following fields:

Attributes	Type	Description
`event`	`string`	The webhook event name. Value: 'MESSAGE_UPDATED'.
`workspaceId`	`number`	The workspace identifier.
`integrationId`	`string`	The integration identifier where the message belongs.
`integrationType`	`string`	The integration type (channel type). Valid values: 'WHATSAPP', 'INSTAGRAM', 'TELEGRAM', 'CUSTOM'.
`status`	`string`	The new message status. Valid values: 'sent', 'delivered', 'read', 'failed'.
`externalMessageId`	`string`	The external message identifier from the provider.
`externalConversationId`	`string`	The external conversation/thread identifier from the provider.
`createdAt`	`string`	The status update timestamp in ISO format.
`traceId`	`string`	Optional tracing identifier.
`spanId`	`string`	Optional tracing span identifier.
`debug`	`boolean`	Optional debug flag.

Here is a JSON example of the payload for a message status update event:

{
  "event": "MESSAGE_UPDATED",
  "workspaceId": 12,
  "integrationId": "6743884f784839ad14770000",
  "integrationType": "WHATSAPP",
  "status": "delivered",
  "externalMessageId": "wamid.HBgLNTUwMDAwMDAwMDAxFQIAERgSMTIzNDU2Nzg5MAA=",
  "externalConversationId": "wamid.conversation.123456",
  "createdAt": "2026-03-09T12:35:46.000Z",
  "traceId": "fb2e0f2a0dc444a4",
  "spanId": "6db90fbf8dd91f53",
  "debug": false
}

For client-related events

The payload that will be sent to the webhook URL will have the following fields:

Attributes	Type	Description
`event`	`string`	The webhook event name. Valid values: 'NEW_CLIENT', 'CLIENT_UPDATED'.
`workspaceId`	`number`	The workspace identifier.
`id`	`string`	The client identifier. This is the client ID of the client who was created or updated.
`email`	`string`	The client email address.
`name`	`string`	The client first name.
`surname`	`string`	The client surname.
`phone`	`string`	The client phone number.
`address`	`string`	The client address.
`city`	`string`	The client city.
`country`	`string`	The client country.
`externalClientId`	`string`	The external client identifier from the integration provider.
`tags`	`array`	The list of tags assigned to the client.
`createdAt`	`string`	The client creation timestamp in ISO format.
`patchedAt`	`string`	The client last update timestamp in ISO format.

Here is a JSON example of the payload for a client-related event:

{
  "event": "CLIENT_UPDATED",
  "workspaceId": 12,
  "id": "67d09433594d52dd19817d60",
  "email": "[email protected]",
  "name": "Temp",
  "surname": "Client",
  "phone": "9055xxxxx371",
  "address": null,
  "city": "Istanbul",
  "country": "Turkey",
  "externalClientId": "9055xxxxx371",
  "tags": ["VIP"],
  "stageId": null,
  "createdAt": "2025-03-11T19:51:15.983Z",
  "patchedAt": "2025-03-11T23:01:34.372Z"
}

For message status update events for SMS/SMPP gateways

The payload that will be sent to the webhook URL will have the following query-string parameters:

Parameter	Type	Description
`message_id`	`string`	The message id.
`status`	`string`	WhatsApp status mapped to SMPP delivery receipt stat.

Status mapping (WhatsApp -> SMPP `stat`)

WhatsApp status	SMPP `stat`
`sent`	`ACCEPTD`
`pending`	`ENROUTE`
`delivered`	`DELIVRD`
`read`	`DELIVRD`
`played`	`DELIVRD`
`failed`	`UNDELIV`

Note: MESSAGE_UPDATED_SMPP is a webhook event type (select it when creating the webhook). The platform will call your URL using HTTP GET and only query-string parameters for this event.

Example

GET https://example.com/dlr?message_id=wamid_ABC123&status=DELIVRD

List Webhooks API

This endpoint returns the Webhooks for a specific workspace. You can search for particular webhooks using a string pattern in the label field or filter by the event field.

Attributes	Type	Description
`workspaceId`	`number`	The workspace ID.
`label`	`string`	The label for this Webhook. May be duplicate with other labels.
`event`	`string`	The event that will trigger the Webhook. Can be 'INCOMING_MESSAGE', 'OUTGOING_MESSAGE', 'MESSAGE_UPDATED', 'ENDING_CONV', 'NEW_CLIENT', 'NEW_CONV', 'CLIENT_UPDATED', or 'ANY_EVENT'.

Request & Response

POST https://gateway.bcrumbs.net/core/gq

query webhooks($input: WebhooksInput!) {
    webhooks(input: $input) {
        nodes {
           workspaceId
           id
           label
           url
           event
           createdAt
        }
    }
}
 
input WebhooksInput {
    workspaceId: Int!
    label: String
    event: WebhookEvent
}

The query above returns JSON structured like this:

{
  "data": {
    "webhooks": {
      "nodes": [
        {
          "workspaceId": 12,
          "id": "67642054b6cc2888638e4600",
          "url": "https://yourwebsite/crm/incoming-messages....",
          "label": "Incoming message webhooks",
          "event": "INCOMING_MESSAGE ",
          "createdAt": "2024-12-19T13:32:04.009Z",
        },
        ...
      ]
    }
  }
}

You can check our playground to explore and interact with GraphQL APIs easily and intuitively with real-time documentation.

Some examples of how to use the webhooks endpoint in different programming languages:

example.sh

curl 'https://gateway.bcrumbs.net/core/gq' \
  -H 'authorization: API-KEY' \
  -H 'content-type: application/json' \
  --data-raw $'{"operationName":"webhooks","variables":{"input":{"workspaceId":12}},"query":"query webhooks($input: WebhooksInput\u0021) {\\n  webhooks(input: $input) {\\n    nodes {\\n      workspaceId\\n      id\\n      label\\n      url\\n      event\\n      createdAt\\n      __typename\\n    }\\n    __typename\\n  }\\n}\\n"}'

Create Webhook API

This endpoint creates a new webhook for a workspace.

Attributes	Type	Description
`workspaceId`	`number`	Required. The workspace ID.
`label`	`string`	Required. The label of the webhook. It can be duplicated with other labels.
`url`	`string`	Required. The webhook URL that receives the event payload.
`event`	`string`	Required. The event that triggers the webhook. Can be 'INCOMING_MESSAGE', 'OUTGOING_MESSAGE', 'MESSAGE_UPDATED', 'ENDING_CONV', 'NEW_CLIENT', 'NEW_CONV', 'CLIENT_UPDATED', or 'ANY_EVENT'.
`headers`	`json`	Optional. Extra headers to send with webhook requests.

Request & Response

POST https://gateway.bcrumbs.net/core/gq

mutation createWebhook($input: WebhookCreateInput!) {
  createWebhook(input: $input) {
    workspaceId
    id
    label
    url
    event
    headers
    createdAt
  }
}
 
input WebhookCreateInput {
  workspaceId: Int!
  label: String!
  url: String!
  event: WebhookEvent!
  headers: JSON
}

The mutation above returns JSON structured like this:

{
  "data": {
    "createWebhook": {
      "workspaceId": 12,
      "id": "67642054b6cc2888638e4600",
      "label": "Incoming message webhooks",
      "url": "https://yourwebsite/crm/incoming-messages",
      "event": "INCOMING_MESSAGE",
      "headers": {
        "x-api-key": "secret-value"
      },
      "createdAt": "2024-12-19T13:32:04.009Z"
    }
  }
}

Programming language examples

curl 'https://gateway.bcrumbs.net/core/gq' \
  -H 'authorization: API-KEY' \
  -H 'content-type: application/json' \
  --data-raw $'{"operationName":"createWebhook","variables":{"input":{"workspaceId":12,"label":"Incoming message webhooks","url":"https://yourwebsite/crm/incoming-messages","event":"INCOMING_MESSAGE","headers":{"x-api-key":"secret-value"}}},"query":"mutation createWebhook($input: WebhookCreateInput!) {\\n  createWebhook(input: $input) {\\n    workspaceId\\n    id\\n    label\\n    url\\n    event\\n    headers\\n    createdAt\\n  }\\n}"}'

Related pages in the app

API Keys Workspace Settings

Webhooks

Overview

In JSON Format

Webhook request payload

For conversation-related events

For message status update events

For client-related events

For message status update events for SMS/SMPP gateways

Status mapping (WhatsApp -> SMPP stat)

Example

List Webhooks API

Request & Response

Create Webhook API

Request & Response

Programming language examples

Related pages in the app

Status mapping (WhatsApp -> SMPP `stat`)