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

message:delivery:failure

Triggered for failed outbound messages from the /reply endpoint.

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

Was this helpful?