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

JavaScriptCurlPythonHTTP

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": [],
    "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

Example: ["notification:delivery:channel","notification:delivery:user","notification:delivery:failure","conversation:read","message:appMaker","message:appUser"]

Response

200

Webhook created successfully

Body

application/json

object

Request

JavaScriptCurlPythonHTTP

const response = await fetch('https://www.channel360.co.za/v1.1/org/{orgId}/webhooks', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "target": "https://41-216-203-43.ngrok-free.app/webhook",
      "triggers": [
        "notification:delivery:channel",
        "notification:delivery:user",
        "notification:delivery:failure",
        "conversation:read",
        "message:appMaker",
        "message:appUser"
      ]
    }),
});
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

JavaScriptCurlPythonHTTP

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
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.

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.