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:

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.

{
  "email": "[e-mail]",
  "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

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

{
  "email": "[e-mail]",
  "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/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.