Webhooks

Webhooks are automated mechanisms for real-time communication between systems, enabling one system to send data to another as soon as a specific event occurs.

---

Managing Webhooks

Note: Webhook triggers can be configured directly from the Channel360 frontend without using the API.

Webhooks

Webhook Triggers

Webhook triggers define which events will result in a webhook request being sent to your endpoint. For example, when a user reads a message, a webhook request is sent containing details about that event

Webhook Target

The webhook target defines the endpoint where Channel360 will send webhook event payloads.

appUserId

Webhook payloads include an appUserId, which uniquely identifies a user within the organisation.

The appUserId is created automatically when a user first interacts with your channel (for example, when they send a message). It can be used to correlate webhook events and to send notifications to that user.

Trigger	Description
notification:delivery:channel	Triggered when a notification is successfully delivered to a customer channel.
notification:delivery:failure	Triggered when a notification fails to be delivered to a customer channel / the user’s device.
notification:delivery:user	Triggered when a notification is successfully delivered to the user’s device.
conversation:read	Triggered when a user has read the conversation.
message:appUser	Triggered for inbound messages (from clients).
message:appMaker	Triggered for outbound messages, which are the messages the user sends in a conversation.
message:delivery:failure	Triggered for failed outbound messages from the /reply endpoint.
flow:submission	Triggered for whatsapp flow submissions.

Example payloads

Use these examples to test your webhook handler and map the fields returned for each event.

notification:delivery:channel

This event is sent when a notification is accepted by the channel (WhatsApp).

{
  "trigger": "notification:delivery:channel",
  "version": "v1.1",
  "app": {
    "_id": "app_example_123456789"
  },
  "timestamp": 1781855992.093,
  "destination": {
    "type": "whatsapp",
    "integrationId": "integration_example_123456",
    "destinationId": "27820000000"
  },
  "isFinalEvent": false,
  "externalMessages": [
    {
      "id": "wamid.EXAMPLE_MESSAGE_ID_1234567890"
    }
  ],
  "notification": {
    "_id": "notification_example_123456"
  },
  "matchResult": {
    "client": {
      "integrationId": "integration_example_123456",
      "externalId": "27820000000",
      "id": "client_example_123456",
      "displayName": "[phone]",
      "status": "active",
      "raw": {
        "from": "27820000000",
        "profile": {
          "name": "Example User"
        }
      },
      "lastSeen": "2026-06-18T12:46:11.066Z",
      "linkedAt": "2022-08-11T21:36:21.156Z",
      "_id": "client_record_example_123456",
      "platform": "whatsapp",
      "active": true,
      "blocked": false,
      "primary": true
    },
    "appUser": {
      "_id": "appuser_example_123456",
      "authenticated": false,
      "conversationStarted": true
    },
    "conversation": {
      "_id": "conversation_example_123456"
    }
  }
}

notification:delivery:user

This event is sent when a notification reaches the user's device.

{
  "trigger": "notification:delivery:user",
  "version": "v1.1",
  "app": {
    "_id": "app_example_123456789"
  },
  "timestamp": 1781855997.352,
  "destination": {
    "type": "whatsapp",
    "integrationId": "integration_example_123456",
    "destinationId": "27820000000"
  },
  "isFinalEvent": true,
  "externalMessages": [
    {
      "id": "wamid.EXAMPLE_MESSAGE_ID_1234567890"
    }
  ],
  "notification": {
    "_id": "notification_example_123456"
  },
  "matchResult": {
    "client": {
      "integrationId": "integration_example_123456",
      "externalId": "27820000000",
      "id": "client_example_123456",
      "displayName": "[phone]",
      "status": "active",
      "raw": {
        "from": "27820000000",
        "profile": {
          "name": "Example User"
        }
      },
      "lastSeen": "2026-06-18T12:46:11.066Z",
      "linkedAt": "2022-08-11T21:36:21.156Z",
      "_id": "client_record_example_123456",
      "platform": "whatsapp",
      "active": true,
      "blocked": false,
      "primary": true
    },
    "appUser": {
      "_id": "appuser_example_123456",
      "authenticated": false,
      "conversationStarted": true
    },
    "conversation": {
      "_id": "conversation_example_123456"
    }
  }
}

conversation:read

This event is sent when the user reads the conversation.

{
  "trigger": "conversation:read",
  "timestamp": 1781856019.856,
  "version": "v1.1",
  "app": {
    "_id": "app_example_123456789"
  },
  "appUser": {
    "_id": "appuser_example_123456",
    "givenName": "Example User",
    "signedUpAt": "2022-08-11T21:36:21.156Z",
    "properties": {},
    "identities": [],
    "authenticated": false,
    "conversationStarted": true
  },
  "conversation": {
    "_id": "conversation_example_123456"
  },
  "client": {
    "integrationId": "integration_example_123456",
    "externalId": "27820000000",
    "id": "client_example_123456",
    "displayName": "[phone]",
    "status": "active",
    "raw": {
      "from": "27820000000",
      "profile": {
        "name": "Example User"
      }
    },
    "lastSeen": "2026-06-18T12:46:11.066Z",
    "linkedAt": "2022-08-11T21:36:21.156Z",
    "_id": "client_record_example_123456",
    "platform": "whatsapp",
    "active": true,
    "blocked": false,
    "primary": true
  },
  "source": {
    "type": "whatsapp",
    "integrationId": "integration_example_123456"
  }
}

notification:delivery:failure

This event is sent when a notification fails to deliver. Use the error object to inspect the failure reason returned by the channel.

{
  "trigger": "notification:delivery:failure",
  "version": "v1.1",
  "app": {
    "_id": "app_example_123456789"
  },
  "timestamp": 1781856153.836,
  "destination": {
    "type": "whatsapp",
    "integrationId": "integration_example_123456",
    "destinationId": "27820000000"
  },
  "isFinalEvent": true,
  "notification": {
    "_id": "notification_example_failed_123456"
  },
  "matchResult": {
    "client": {
      "integrationId": "integration_example_123456",
      "externalId": "27820000000",
      "id": "client_example_123456",
      "displayName": "[phone]",
      "status": "active",
      "raw": {
        "from": "27820000000",
        "profile": {
          "name": "Example User"
        }
      },
      "lastSeen": "2026-06-18T12:46:11.066Z",
      "linkedAt": "2022-08-11T21:36:21.156Z",
      "_id": "client_record_example_123456",
      "platform": "whatsapp",
      "active": true,
      "blocked": false,
      "primary": true
    },
    "appUser": {
      "_id": "appuser_example_123456",
      "authenticated": false,
      "conversationStarted": true
    },
    "conversation": {
      "_id": "conversation_example_123456"
    }
  },
  "error": {
    "code": "uncategorized_error",
    "underlyingError": {
      "message": "(#132001) Template name does not exist in the translation",
      "code": 132001,
      "type": "OAuthException",
      "error_data": {
        "messaging_product": "whatsapp",
        "details": "template name (example_template_name) does not exist in en"
      },
      "fbtrace_id": "FBTRACE_EXAMPLE_123456"
    }
  }
}

message:appUser

This event is sent when a client sends an inbound message.

The example uses fictional data. It includes one prior notification.

{
  "trigger": "message:appUser",
  "version": "v1.1",
  "app": {
    "_id": "app_example_123456789"
  },
  "appUser": {
    "_id": "appuser_example_123456",
    "givenName": "Example User",
    "signedUpAt": "2026-07-15T13:19:56.559Z",
    "properties": {},
    "identities": [],
    "authenticated": false,
    "conversationStarted": true
  },
  "conversation": {
    "_id": "conversation_example_123456"
  },
  "client": {
    "_id": "client_record_example_123456",
    "integrationId": "integration_example_123456",
    "externalId": "27820000000",
    "id": "client_example_123456",
    "displayName": "[phone]",
    "status": "active",
    "raw": {
      "from": "27820000000",
      "profile": {
        "name": "Example User"
      }
    },
    "lastSeen": "2026-07-15T13:19:56.559Z",
    "linkedAt": "2026-07-15T13:19:56.559Z",
    "platform": "whatsapp",
    "active": true,
    "blocked": false,
    "primary": true
  },
  "recentNotifications": [
    {
      "source": {
        "type": "notification",
        "id": "notification_example_123456"
      },
      "role": "appMaker",
      "authorId": "author_example_123456",
      "type": "text",
      "text": "Would you like us to contact you about this offer?",
      "received": 1784121596.587,
      "actions": [
        {
          "type": "reply",
          "text": "Yes please",
          "uri": "",
          "payload": "Yes please",
          "_id": "action_example_123456"
        }
      ],
      "_id": "notification_message_example_123456"
    }
  ],
  "messages": [
    {
      "role": "appUser",
      "source": {
        "type": "whatsapp",
        "id": "client_example_123456",
        "integrationId": "integration_example_123456",
        "originalMessageId": "wamid.EXAMPLE_MESSAGE_ID_1234567890",
        "originalMessageTimestamp": 1784121593
      },
      "authorId": "appuser_example_123456",
      "name": "Example User",
      "_id": "message_example_123456",
      "type": "text",
      "received": 1784121596.587,
      "text": "Hello"
    }
  ]
}

recentNotifications is optional. It may be absent when the conversation has no earlier messages.

{
  "trigger": "message:appUser",
  "messages": [
    {
      "type": "text",
      "text": "Hello"
    }
  ]
}

flow:submission

This event is sent when a user submits a WhatsApp Flow.

The example uses fictional data. Parse response_json to access submitted fields.

{
  "events": [
    {
      "id": "flow_submission_example_123456",
      "createdAt": "2026-07-16T08:05:49.907Z",
      "type": "flow:submission",
      "payload": {
        "conversation": {
          "id": "conversation_example_123456",
          "type": "personal"
        },
        "source": {
          "type": "whatsapp",
          "integrationId": "integration_example_123456"
        },
        "user": {
          "id": "appuser_example_123456",
          "authenticated": false
        },
        "passthroughType": "interactive",
        "passthroughPayload": {
          "from": "27820000000",
          "id": "wamid.EXAMPLE_MESSAGE_ID_1234567890",
          "timestamp": "1784189148",
          "type": "interactive",
          "interactive": {
            "type": "nfm_reply",
            "nfm_reply": {
              "response_json": "{\"monthly_income\":\"25000\",\"living_expenses\":\"12000\",\"preferred_store\":\"Example Store\",\"receive_marketing\":true,\"first_name\":\"Example\",\"surname\":\"User\",\"id_number\":\"9001015009087\",\"cellphone\":\"27820000000\",\"email\":\"[e-mail]\",\"flow_token\":\"example-flow-token\"}"
            }
          }
        }
      }
    }
  ],
  "trigger": "flow:submission"
}

Create Webhook

POST https://www.channel360.co.za/v1.1/org/{{orgId}}/webhooks

{
    "target": "{{targetURL}}",
    "triggers": [
        "notification:delivery:channel",
        "notification:delivery:user",
        "notification:delivery:failure",
        "conversation:read",
        "message:appMaker",
        "message:appUser"
    ]
}

Get Webhooks

GET https://www.channel360.co.za/v1.1/org/{{orgId}}/webhooks

    {
        "organization": "{{yourOrgId}}",
        "target": "{{targetURL}}",
        "triggers": [
            "message:appUser",
            "message:appMaker",
            "notification:delivery:user",
            "message:delivery:failure",
            "conversation:read",
            "notification:delivery:channel",
            "notification:delivery:failure"
        ],
        "createdAt": "2025-11-04T14:59:01.000Z",
        "updatedAt": "2025-11-04T14:59:01.000Z",
        "version": 0,
        "id": "webhook_example_123456"
    }

Delete Webhook

DELETE https://www.channel360.co.za/v1.1/org/{{orgId}}/webhooks/{{webhook-id}}

Path Parameters

Field	Type	Description
orgId	string required	Your Organization ID
webhook-id	string required	Unique identifier of the webhook

Retry Policy

A webhook call will be attempted up to 5 times over a 15 minute window. The attempts will happen at an exponentially increasing interval if the target responds with anything but a success (2XX) or a non-recoverable error. If no response is received within 20 seconds, the call will be considered a failure and will also be reattempted.

Non-recoverable Errors

The following status codes are deemed to be non-recoverable and Channel Mobile will not reattempt a call when receiving a response with them:

• 400: The target exists, but can’t process the payload.

• 401: The target is behind authentication or doesn’t recognize the webhook secret.

• 403: Channel Mobile should not be calling the target.

• 404: The target doesn’t exist.

• 406: The target exists, and rejected the webhook intentionally.