# Webhooks

***

### Managing Webhooks

{% hint style="warning" %}
**Note:** Webhook triggers can be configured directly from the Channel360 frontend without using the API.
{% endhint %}

{% content-ref url="../../channel360-guide/webhooks" %}
[webhooks](https://docs.channel360.co.za/channel360-guide/webhooks)
{% endcontent-ref %}

### Webhook Triggers

Webhook triggers define which events will result in a webhook request being sent to your endpoint.\
For example, when a user reads a message, a webhook request is sent containing details about that event

### Webhook Target

The webhook target defines the endpoint where Channel360 will send webhook event payloads.

#### appUserId

Webhook payloads include an `appUserId`, which uniquely identifies a user within the organisation.

The `appUserId` is created automatically when a user first interacts with your channel (for example, when they send a message). It can be used to correlate webhook events and to send notifications to that user.

| 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.                             |
| flow:submission               | Triggered for whatsapp flow submissions.                                                       |

## Create Webhook

<mark style="color:yellow;">`POST`</mark> `https://www.channel360.co.za/v1.1/org/{{orgId}}/webhooks`

```json
{
    "target": "{{targetURL}}",
    "triggers": [
        "notification:delivery:channel",
        "notification:delivery:user",
        "notification:delivery:failure",
        "conversation:read",
        "message:appMaker",
        "message:appUser"
    ]
}
```

## Get Webhooks

<mark style="color:green;">`GET`</mark> `https://www.channel360.co.za/v1.1/org/{{orgId}}/webhooks`

```json
    {
        "organization": "{{yourOrgId}}",
        "target": "{{targetURL}}",
        "triggers": [
            "message:appUser",
            "message:appMaker",
            "notification:delivery:user",
            "message:delivery:failure",
            "conversation:read",
            "notification:delivery:channel",
            "notification:delivery:failure"
        ],
        "createdAt": "2025-11-04T14:59:01.000Z",
        "updatedAt": "2025-11-04T14:59:01.000Z",
        "version": 0,
        "id": "690a14b4f56fcf6220b5a1af"
    }
```

## Delete Webhook

<mark style="color:orange;">`DELETE`</mark> `https://www.channel360.co.za/v1.1/org/{{orgId}}/webhooks/{{webhook-id}}`

### Path Parameters

| Field      | Type                                                                         | Description                      |
| ---------- | ---------------------------------------------------------------------------- | -------------------------------- |
| orgId      | string <sup><mark style="color:red;">required<mark style="color:red;"></sup> | Your Organization ID             |
| webhook-id | string <sup><mark style="color:red;">required<mark style="color:red;"></sup> | Unique identifier of the webhook |

## 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](https://docs.smooch.io/rest/#non-recoverable-errors). If no response is received within 20 seconds, the call will be considered a failure and will also be reattempted.

#### Non-recoverable Errors <a href="#non-recoverable-errors" id="non-recoverable-errors"></a>

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.