Webhooks

Open in the app: Webhooks

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

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.
`sourceType`	`string`	Optional. The referral source type when the message originated from an ad or referral link. Included on `INCOMING_MESSAGE` and `NEW_CONV` when available.
`sourceUrl`	`string`	Optional. The referral source URL when the message originated from an ad or referral link. Included on `INCOMING_MESSAGE` and `NEW_CONV` when available.

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",
  "sourceType": "ad",
  "sourceUrl": "https://fb.me/abc123",
  "debug": false
}

Referral attribution: sourceType and sourceUrl are only included when the channel provides referral metadata (for example, a WhatsApp click-to-chat ad or a Facebook Messenger referral). They are omitted from the payload when not available.

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
}

The payload includes the full Client record plus event. integrationId and integrationType are included only on NEW_CLIENT (the channel where the contact first messaged). CLIENT_UPDATED sends the client record only.

Which Client fields are usually filled at creation depends on the channel — see the per-channel matrix.

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.
`integrationId`	`string`	`NEW_CLIENT` only. The integration (channel) id where the first inbound message was received.
`integrationType`	`string`	`NEW_CLIENT` only. The integration type (channel type). Valid values: 'WHATSAPP', 'WA_GUPSHUP', 'FACEBOOK', 'INSTAGRAM', 'TELEGRAM', 'CUSTOM', 'BCWEBCHAT'.
`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.
`avatarUrl`	`string`	Profile picture URL from the external channel, when available.
`externalClientId`	`string`	The external client identifier from the integration provider.
`integrationId`	`string`	Optional. The integration identifier. Included on `NEW_CLIENT` when the client is created from an incoming channel message.
`integrationType`	`string`	Optional. The integration type (channel type). Included on `NEW_CLIENT` when the client is created from an incoming channel message.
`sourceType`	`string`	Optional. The referral source type when the new client was created from an incoming message with referral metadata. Only included on `NEW_CLIENT` when available.
`sourceUrl`	`string`	Optional. The referral source URL when the new client was created from an incoming message with referral metadata. Only included on `NEW_CLIENT` when available.
`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. Present on `CLIENT_UPDATED` when the client was edited.

Here is a JSON example of the payload for NEW_CLIENT:

{
  "event": "NEW_CLIENT",
  "workspaceId": 12,
  "id": "67d09433594d52dd19817d60",
  "integrationId": "6743884f784839ad14770000",
  "integrationType": "INSTAGRAM",
  "email": null,
  "name": "Jane",
  "surname": null,
  "phone": null,
  "address": null,
  "city": null,
  "country": null,
  "avatarUrl": "https://fbcdn.example/profile.jpg",
  "externalClientId": "17841400000000000",
  "tags": [],
  "stageId": null,
  "createdAt": "2025-03-11T19:51:15.983Z"
}

Here is a JSON example of the payload for CLIENT_UPDATED:

{
  "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"
}

Here is a JSON example of the payload for a NEW_CLIENT event created from an incoming referral message:

{
  "event": "NEW_CLIENT",
  "workspaceId": 12,
  "id": "67d09433594d52dd19817d60",
  "name": "Temp",
  "surname": "Client",
  "phone": "9055xxxxx371",
  "externalClientId": "9055xxxxx371",
  "integrationId": "6743884f784839ad14770000",
  "integrationType": "WHATSAPP",
  "sourceType": "ad",
  "sourceUrl": "https://fb.me/abc123",
  "createdAt": "2025-03-11T19:51:15.983Z"
}

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"}'

example.py

import requests
 
headers = {
    'authorization': 'API-KEY',
    'content-type': 'application/json',
}
 
json_data = {
    'operationName': 'webhooks',
    'variables': {
        'input': {
            'workspaceId': 12,
        },
    },
    'query': 'query webhooks($input: WebhooksInput!) {\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',
}
 
response = requests.post('https://gateway.bcrumbs.net/core/gq', headers=headers, json=json_data)

example.js

import axios from 'axios';
 
const response = await axios.post(
  'https://gateway.bcrumbs.net/core/gq',
  {
    operationName: 'webhooks',
    variables: {
      input: {
        workspaceId: 12
      }
    },
    query: 'query webhooks($input: WebhooksInput!) {\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'
  },
  {
    headers: {
      authorization: 'API-KEY',
      'content-type': 'application/json',
    }
  }
);

example.cs

using System.Net.Http;
using System.Net.Http.Headers;
 
HttpClient client = new HttpClient();
 
HttpRequestMessage request = new HttpRequestMessage(HttpMethod.Post, "https://gateway.bcrumbs.net/core/gq");
 
request.Headers.Add("accept", "application/json");
request.Headers.Add("authorization", "API-KEY");
 
request.Content = new StringContent("{\"operationName\":\"webhooks\",\"variables\":{\"input\":{\"workspaceId\":12}},\"query\":\"query webhooks($input: WebhooksInput!) {\\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\"}");
request.Content.Headers.ContentType = new MediaTypeHeaderValue("application/json");
 
HttpResponseMessage response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
string responseBody = await response.Content.ReadAsStringAsync();

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}"}'

import requests
 
headers = {
    'authorization': 'API-KEY',
    'content-type': 'application/json',
}
 
json_data = {
    '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}\n',
}
 
response = requests.post('https://gateway.bcrumbs.net/core/gq', headers=headers, json=json_data)

import axios from 'axios';
 
const response = await axios.post(
  'https://gateway.bcrumbs.net/core/gq',
  {
    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}\n'
  },
  {
    headers: {
      authorization: 'API-KEY',
      'content-type': 'application/json',
    }
  }
);

using System.Net.Http;
using System.Net.Http.Headers;
 
HttpClient client = new HttpClient();
 
HttpRequestMessage request = new HttpRequestMessage(HttpMethod.Post, "https://gateway.bcrumbs.net/core/gq");
 
request.Headers.Add("accept", "application/json");
request.Headers.Add("authorization", "API-KEY");
 
request.Content = new StringContent("{\"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}\\n\"}");
request.Content.Headers.ContentType = new MediaTypeHeaderValue("application/json");
 
HttpResponseMessage response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
string responseBody = await response.Content.ReadAsStringAsync();

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`)