> ## Documentation Index
> Fetch the complete documentation index at: https://developer.hubmessage.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> Receive real-time events from Hub Message in your system via webhooks

export const projectName = 'Hub Message';

## What are webhooks?

Webhooks are HTTP notifications that {projectName} sends to your server when events happen on a channel — such as a message received, delivery status, or connection change.

Instead of your system periodically polling the API, {projectName} **pushes events to you** as they happen.

```
Customer sends message → Hub Message → POST to your URL → Your system processes it
```

<Note>
  Webhooks require the **ENTERPRISE** role on your account. If your account does not have this role, webhook CRUD calls return `422`. Contact support to enable it.
</Note>

## Available events

| Event                   | When it is triggered                       |
| ----------------------- | ------------------------------------------ |
| `MESSAGE_RECEIVED`      | A message was received on the channel      |
| `MESSAGE_DELIVERY`      | Delivery confirmation for a sent message   |
| `MESSAGE_STATUS`        | Message status update (read, failed, etc.) |
| `RECEIVED_STATUS`       | Combined received and status               |
| `RECEIVED_AND_DELIVERY` | Combined received and delivery             |
| `CONNECTED`             | The channel was connected                  |
| `DISCONNECTED`          | The channel was disconnected               |
| `PRESENCE_CHAT`         | Contact presence or typing indicator       |
| `INITIAL_DATA`          | Initial data sync when channel connects    |
| `BLOCK`                 | Contact block event                        |

## Payload formats

{projectName} supports three payload formats:

| Format    | Description                 |
| --------- | --------------------------- |
| `DEFAULT` | Standard Hub Message format |

## Webhook authentication

You can configure how {projectName} authenticates when calling your URL:

| Type            | How it works                                           |
| --------------- | ------------------------------------------------------ |
| `NONE`          | No authentication (not recommended in production)      |
| `BEARER`        | Sends `Authorization: Bearer <token>`                  |
| `API_KEY`       | Sends a configured API key                             |
| `BASIC`         | HTTP Basic Authentication (`username:password`)        |
| `CUSTOM_HEADER` | Sends a custom header with a name and value you define |

## HMAC signing

To ensure requests received are genuinely from {projectName} and have not been tampered with, enable HMAC signing by setting `signing: true` when creating the webhook.

When enabled:

* A 64-character hexadecimal `secret` is generated and returned **only once** on create/update.
* Each request sent to your webhook includes a header with an HMAC-SHA256 signature computed over the payload.
* You verify the signature on your server using the stored `secret`.

<Warning>
  The `secret` is shown **only** in the `POST /webhooks` (create) or `PATCH /webhooks/{id}` (update with `signing: true`) response. Store it securely — it cannot be retrieved afterwards.
</Warning>

## Per channel

Each webhook is associated with a specific channel via `channelId`. A single channel can have **multiple webhooks** with different configurations — for example, one for messages and another for connection events.

## Management

<CardGroup cols={2}>
  <Card title="Create webhook" icon="plus" href="/en/webhooks/create-webhook">
    Register a new webhook endpoint on a channel.
  </Card>

  <Card title="List webhooks" icon="list" href="/en/webhooks/list-webhooks">
    View all webhooks for a channel.
  </Card>

  <Card title="Update webhook" icon="pen" href="/en/webhooks/update-webhook">
    Update URL, events, authentication, or status.
  </Card>

  <Card title="Delete webhook" icon="trash" href="/en/webhooks/delete-webhook">
    Remove a webhook from a channel.
  </Card>

  <Card title="Payload structure" icon="brackets-curly" href="/en/webhooks/payloads">
    Real payload examples received for each message type.
  </Card>
</CardGroup>