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

Get Webhooks

API request for Webhooks

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

Path parameters

orgId*string

Response

200

Successfully retrieved Webhooks

Body

application/json

conversationobject

Request

JavaScriptCurlPython

const response = await fetch('https://www.channel360.co.za/v1.1/org/{orgId}/:webhooks', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

{
  "conversation": {
    "triggers": [
      [
        "notification:delivery:channel",
        "notification:delivery:user",
        "notification:delivery:failure",
        "conversation:read",
        "message:appMaker",
        "message:appUser"
      ]
    ],
    "organization": "421454989fb27b088b1859",
    "target": "https://41-216-203-43.ngrok-free.app/webhook",
    "createdAt": "2023-11-28T09:01:42.786Z",
    "updatedAt": "2023-11-28T09:01:42.786Z",
    "version": 0,
    "id": "69390n980c76ff6d887r7"
  }
}

Want to create a Webhook?

This endpoint allows you to create a webhook.

Create Webhook

Create Webhook

API call to Create a Webhook

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

Path parameters

orgId*string

Body

application/json

targetstring

Example: "https://41-216-203-43.ngrok-free.app/webhook"

triggersobject

Response

200

Webhook created successfully

Body

application/json

object

Request

JavaScriptCurlPython

const response = await fetch('https://www.channel360.co.za/v1.1/org/{orgId}/webhooks', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

200

{}

Want to remove a Webhook?

This endpoint allows you to delete a specific webhook by its unique identifier (webhook-id).

Delete Webhook

Delete Webhook

API call to Delete a Webhook

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

Path parameters

orgId*string

webhook-id*string

Response

200

Webhook deleted successfully

Body

application/json

object

Request

JavaScriptCurlPython

const response = await fetch('https://www.channel360.co.za/v1.1/org/{orgId}/webhooks/{webhook-id}', {
    method: 'DELETE',
    headers: {},
});
const data = await response.json();

Response

200

{}

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: a channel finds a user that matches the information provided a client is activated a user unsubscribes from a conversation or blocks the app
conversation:create	When a new conversation is created.
conversation:leave	When a participant leaves a sdkGroup conversation.
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.