Webhooks
What are Webhooks, and how to use them
What are 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.
Want your organisations Webhooks?
This endpoint allows you to retrieve information about webhooks associated with a specific organisation.
Get Webhooks
Want to create a Webhook?
This endpoint allows you to create a webhook.
Create Webhook
Want to remove a Webhook?
This endpoint allows you to delete a specific webhook by its unique identifier (webhook-id).
Delete Webhook
Webhook Triggers
Trigger | Description |
---|---|
client:add | When initiating a channel link or when an SDK client is created. |
client:remove | When a client is updated. This can happen when:
|
conversation:create | When a new conversation is created. |
conversation:leave | When a participant leaves a |
conversation:remove | When a conversation is deleted. |
conversation:message | When a new message was sent in the conversation. |
conversation:message:delivery:channel | When a message is successfully delivered to a channel. |
conversation:message:delivery:failure | When a new message fails to be delivered in the conversation. |
conversation:message:delivery:user | When a new message is successfully delivered to a user. |
conversation:postback | When a user clicks on a postback action button. |
conversation:read | When a user has read the conversation. |
conversation:referral | When a user is referred to a conversation. |
conversation:typing | When a user starts or stops typing. |
switchboard:acceptControl | When a switchboard integration accepts control of a conversation. |
switchboard:acceptControl:failure | When control of a conversation fails to be accepted by a switchboard integration. |
switchboard:offerControl | When a switchboard integration has been offered control of the conversation. |
switchboard:offerControl:failure | When control of a conversation can't be offered to another switchboard integration. |
switchboard:passControl | When a switchboard integration gives control of the conversation to another switchboard integration. |
switchboard:passControl:failure | When changing a switchboard integration to active fails. |
user:merge | When two or more users are merged into one. |
user:update | When a user is updated. (Currently, when a user's identification is updated.) |
message:appMaker | The message the user sends in a conversation |
notification:delivery:channel | When a notification is successfully delivered to a customer channel |
notification:delivery:user | When a notification is successfully delivered to the user’s device |
notification:delivery:failure | When a notification fails to be delivered to a customer channel or the user’s device |
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.
Last updated