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

get

API request for Webhooks

Path parameters

orgIdstringRequired

Responses

200

Successfully retrieved Webhooks

application/json

get

HTTPcURLJavaScriptPython

GET /v1.1/org/{orgId}/:webhooks HTTP/1.1
Host: www.channel360.co.za
Accept: */*

200

Successfully retrieved Webhooks

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

post

API call to Create a Webhook

Path parameters

orgIdstringRequired

Body

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

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

Responses

200

Webhook created successfully

application/json

Responseobject

post

HTTPcURLJavaScriptPython

POST /v1.1/org/{orgId}/webhooks HTTP/1.1
Host: www.channel360.co.za
Content-Type: application/json
Accept: */*
Content-Length: 220

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

200

Webhook created successfully

{}

Want to remove a Webhook?

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

Delete Webhook

Delete Webhook

delete

API call to Delete a Webhook

Path parameters

orgIdstringRequired

webhook-idstringRequired

Responses

200

Webhook deleted successfully

application/json

Responseobject

delete

HTTPcURLJavaScriptPython

DELETE /v1.1/org/{orgId}/webhooks/{webhook-id} HTTP/1.1
Host: www.channel360.co.za
Accept: */*

200

Webhook deleted successfully

{}

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.