> For the complete documentation index, see [llms.txt](https://docs.cuoral.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cuoral.com/message-event.md).

# Message Event

The `message` event is triggered when a new message is created in a conversation.

Cuoral sends this event to the organization's registered webhook `target_url`.

### Event Type

The `X-Event` header identifies the type of webhook event.

For message events:

```http
X-Event: message
```

### Request Headers

A message webhook includes the following headers:

| Header                       | Description                                                     |
| ---------------------------- | --------------------------------------------------------------- |
| `Content-Type`               | The content type of the request. Always `application/json`.     |
| `X-Event`                    | The webhook event type. For this event, the value is `message`. |
| `X-Cuoral-Webhook-Signature` | HMAC-SHA256 signature used to authenticate the webhook request. |

For information about verifying webhook signatures, see the **Webhook Authentication** page.

### Payload

The message event payload contains information about the customer and the message.

```json
{
  "email": "customer@example.com",
  "name": "John Doe",
  "message": "Hello, I need help with my account.",
  "sender": "customer"
}
```

### Payload Fields

| Field     | Type     | Description                                                         |
| --------- | -------- | ------------------------------------------------------------------- |
| `email`   | `string` | The email address of the customer associated with the conversation. |
| `name`    | `string` | The name of the customer associated with the conversation.          |
| `message` | `string` | The text content of the message.                                    |
| `sender`  | `string` | Identifies who sent the message.                                    |

#### `sender`

The `sender` field indicates who created the message.

| Value      | Description                                               |
| ---------- | --------------------------------------------------------- |
| `customer` | The message was sent by the customer.                     |
| `internal` | The message was sent by an internal agent, admin, or bot. |

### Example Request

```http
POST /webhooks/cuoral HTTP/1.1
Content-Type: application/json
X-Event: message
X-Cuoral-Webhook-Signature: <signature>

{
  "email": "customer@example.com",
  "name": "John Doe",
  "message": "Hello, I need help with my account.",
  "sender": "customer"
}
```

### Response

Your webhook endpoint should return one of the following status codes to acknowledge successful receipt:

* `200 OK`
* `201 Created`
* `204 No Content`

For example:

```http
HTTP/1.1 200 OK
```

### Retries

If your endpoint responds with any status code other than `200`, `201`, or `204`, Cuoral will retry the webhook delivery.

Cuoral will attempt to deliver the webhook up to **3 additional times** using an exponential backoff strategy.

Your webhook handler should therefore be **idempotent** and safely handle the same event being received more than once.