Webhook Payloads

Webhooks in Arattai Business Platform notify businesses in real time when specific events occur. Instead of having to check for updates, Arattai proactively sends event information to a configured webhook URL whenever an action takes place.

Webhook URL Requirements

When configuring a webhook URL, ensure that it meets the following requirements:

The URL must use HTTPS. Plain HTTP URLs are rejected.
The URL must not exceed 2048 characters.
The endpoint must allow a verification request to confirm it is active and owned by the configuring user.
The webhook configuration supports up to two shared secrets, with only one active at any given time.
A single webhook URL can be reused across multiple configurations.
Event notifications can be paused or resumed independently for each webhook configuration.

Webhook URL Validation

To validate a webhook URL, Arattai sends a GET request to the endpoint containing a single challenge UUID as a query parameter.

The webhook endpoint must respond with HTTP 200 and a JSON body echoing back the exact challenge value:

{"challenge": "<uuid>"}

The webhook URL is valid only if the response returns the exact challenge UUID. This step ensures the endpoint is reachable and securely controlled by the user configuring the webhook.

Webhook Data Integrity

When configuring a webhook URL, businesses can generate a secret key to secure event delivery. For every webhook event sent by Arattai, an encrypted signature of the payload is included in the request header along with an event ID:


X-Hub-Signature-256: sha256=<Base64-encoded-HmacSHA256-signature>
x-arattai-eventid: <unique-event-id>

This signature allows your system to verify that the webhook request originated from Arattai and that the payload has not been tampered with in transit. To validate the request, compute the HMAC-SHA256 of the raw request body using the secret key generated during webhook configuration, then Base64-encode the result and compare it with the value after sha256= in the X-Hub-Signature-256 header.

Note: Despite the header name following GitHub's convention (which uses hex), Arattai encodes the signature as Base64, not hex.

The x-arattai-eventid header contains a unique identifier for each webhook delivery and is present on every request.

For business users: The signature must be verified using the HmacSHA256 algorithm with Base64 encoding to ensure request authenticity.

Note: The X-Hub-Signature-256 header is only sent when the webhook has a secret key configured and selected. If no key is selected, the header is omitted from the request.

The webhook payload is the data sent in the HTTP request body from Arattai to a webhook endpoint when an event is triggered. This payload contains event-specific information, including timestamps, identifiers, and details about the associated user or message. It is an incoming request intended to be consumed and processed by the business.

Upon receiving a payload, businesses can trigger workflows such as logging activities, updating customer records, and initiating follow-up communications. This enables an event-driven approach, reducing the need for manual intervention and fostering more responsive customer interactions.

The webhook payload sent from Arattai to your endpoint is wrapped in a top-level envelope. The inner event-specific data is nested under the entity field:


{
    "event": "chat.message.received",
    "version": "1",
    "attempt": 1,
    "event_time": 1786709296458,
    "workflow": {
        "id": "182731000000067001"
    },
    "business_id": "182731000000000001",
    "phonenumber_id": "182731000000012345",
    "company_id": "182731000000000002",
    "entity": {
        "...event-specific payload..."
    }
}

Note: The attempt field is always 1. It is not a retry counter - on retries, the exact same original payload is resent.

Note: event_time is a Unix epoch timestamp in milliseconds (number), not an ISO/UTC date-time string.

The event-specific payloads below describe the content of the entity field for each event type.

Types of Webhook payloads

The table below outlines the supported webhook payloads along with their respective request formats.

chat.message.received

Triggered when the business receives a message from the customer. See Message received webhook event payloads below for the detailed payload format defined for each message type.

chat.message.reacted

Triggered when a customer reacts to a message sent by the business.


{
    "content": {
        "emoji": "👍"
    },
    "user": {
        "name": "Ryan West",
        "id": "970123457"
    },
    "ack_key": "17631072821836",
    "id": "1012382113_437281136"
}

chat.message.edited

Triggered when a customer edits a message previously sent to the business.


{
    "content": {
        "message": "Updated message text"
    },
    "user": {
        "name": "Ryan West",
        "id": "970123457"
    },
    "type": "text",
    "ack_key": "1763107281836",
    "id": "1763107282113_45120363436"
}

chat.message.unreacted

Triggered when a customer removes their reaction to a message sent by the business.

Note: Removing a reaction is not currently supported in the Arattai app; this event is reserved for future support and may not be delivered.


{
    "content": {
        "emoji": "👍"
    },
    "user": {
        "name": "Ryan West",
        "id": "970123457"
    },
    "ack_key": "1763107281836",
    "id": "1763107282113_45120363436"
}

user.preference.updated

Triggered when a customer updates their preferences for business-initiated messages.


{
    "data_sharing": {
        "name": "allowed|denied",
        "phone": "allowed|denied"
    },
    "subscription": true
}

miniapp.closed

Triggered when a customer closes a mini app.


{
    "id": "$miniappId",
    "status": "closed",
    "user": {
        "name": "Ryan West",
        "id": "970123457"
    }
}

chat.message.sent

Triggered when a message is successfully sent to a customer by the business.


{
    "ack_key": "1763107281836",
    "id": "1763107282113_45120363436"
}

chat.message.delivered

Triggered when a message sent by the business is delivered to the customer's device.


{
    "ack_key": "1763107281836",
    "id": "1763107282113_45120363436"
}

chat.message.failed

Triggered when a message sent by a business to a customer fails.


{
    "ack_key": "1763107281836"
}

chat.message.deleted

Triggered when a message sent to a customer is deleted.


{
    "content": "...content of the deleted message...",
    "type": "text",
    "user": {
        "name": "Ryan West",
        "id": "970123457"
    },
    "time": 1786713738236,
    "ack_key": "1763107281836",
    "id": "1763107282113_45120363436"
}

messagetemplate.approval.updated

Triggered when the approval status of a message template is updated.


{
    "template_id": "$templateId",
    "status": "approved|rejected"
}

Message received webhook event payloads

The table below details the supported webhook payloads for the chat.message.received event, specified for each message type.

Text

Triggered when a business receives a text message.


{
    "content": "Hey There!",
    "user": {
        "name": "Ryan West",
        "id": "970123457"
    },
    "type": "text",
    "ack_key": "1763107281836"
}

If the message is a reply to a message, the following is the format:


{
    "content": "ok",
    "user": {
        "name": "Ryan West",
        "id": "970123457"
    },
    "ack_key": "1763107281836",
    "id": "1763107282113_45120363436",
    "replied_to": {
        "ack_key": "1763107281836",
        "id": "1763107282113_45120363436"
    }
}

Quick Reply

Triggered when a business receives a quick reply.


{
    "content": "hii",
    "user": {
        "name": "Ryan West",
        "id": "970123457"
    },
    "type": "text",
    "ack_key": "1763107281836"
}

Interactive List

Triggered when a business receives a customer's response to an interactive list.


{
    "content": {
        "title": "Top variant",
        "description": "1767335004660",
        "message": "XZ+O",
        "button_id": "1767335004660"
    },
    "user": {
        "name": "Ryan West",
        "id": "970123457"
    },
    "type": "list_input",
    "ack_key": "1763107281836"
}

Address

Triggered when a business receives an address as a customer's response.


{
    "content": {
        "message": "Scott Fisher\n+919XXXXXXXX\nDunder Mifflin",
        "id": "address_1",
        "name": "Scott Fisher",
        "phone": "+919XXXXXXXX",
        "zip_code": "18507",
        "address": "Dunder Mifflin Village, Scranton",
        "landmark": "Paper Company",
        "flat": "2/278",
        "floor": "First Floor",
        "save_address": true
    },
    "user": {
        "name": "Ryan West",
        "id": "970123457"
    },
    "type": "address",
    "ack_key": "1763107281836"
}

Image

Triggered when a business receives an image from a customer.


{
    "content": {
        "file_name": "istockphoto-1435226078-612x612.jpg",
        "size": "30000",
        "type": "image/jpeg",
        "thumbnail": {
            "image_data": "<base64-encoded-thumbnail>",
            "dimensions": {
                "width": 740,
                "height": 1109
            }
        },
        "url": "$udsLink",
        "comment": "hello",
        "dimensions": {
            "width": 740,
            "height": 1109
        }
    },
    "user": {
        "name": "Ryan West",
        "id": "970123457"
    },
    "type": "file",
    "ack_key": "1763107281836"
}

Video

Triggered when a business receives a video from a customer.


{
    "content": {
        "duration": 33,
        "file_name": "BMW M3 Competition - 4K Cinematic Short Video.mp4",
        "size": "4871732",
        "type": "video/quicktime",
        "thumbnail": {
            "image_data": "<base64-encoded-thumbnail>",
            "dimensions": {
                "width": 740,
                "height": 1109
            }
        },
        "url": "$udsLink",
        "comment": "hello",
        "dimensions": {
            "height": 720,
            "width": 1280
        }
    },
    "user": {
        "name": "Ryan West",
        "id": "970123457"
    },
    "type": "file",
    "ack_key": "1763107281836"
}

Audio

Triggered when a business receives audio from a customer.


{
    "content": {
        "file_name": "voice_1280853219917051885_1764154706935.wav",
        "size": "4871732",
        "type": "audio/vnd.wave",
        "url": "$udsLink"
    },
    "user": {
        "name": "Ryan West",
        "id": "970123457"
    },
    "type": "file",
    "ack_key": "1763107281836"
}

Location

Triggered when a business receives a location from a customer.


{
    "content": {
        "location": "Tamil Nadu",
        "longitude": "77.3360491",
        "name": "2/278, Dunder Mifflin Village, Scranton, Tenkasi, Pennsylvania",
        "loc_type": "current|pinned",
        "latitude": "8.9029121"
    },
    "user": {
        "name": "Ryan West",
        "id": "970123457"
    },
    "type": "location",
    "ack_key": "1763107281836"
}

Contact

Triggered when a business receives a contact from a customer.


{
    "content": {
        "addresses": [
            {
                "zip_code": "627814",
                "country": "India",
                "city": "Tenkasi",
                "street": "",
                "state": "Tamil nadu",
                "type": "home"
            }
        ],
        "name": "Sargunam Durairaj",
        "phones": [
            {
                "phone": "",
                "type": "home|work|personal|other"
            }
        ],
        "emails": [
            {
                "email_id": "",
                "type": "personal|work"
            }
        ],
        "links": [
            {
                "link": "",
                "type": "work|personal|fb|insta"
            }
        ],
        "company": {
            "name": "Arattai Business Platform",
            "department": "Arattai",
            "job_title": "MLS"
        }
    },
    "user": {
        "name": "Ryan West",
        "id": "970123457"
    },
    "type": "contact",
    "ack_key": "1763107281836"
}

Document

Triggered when a business receives a document from a customer.


{
    "content": {
        "file_name": "testing.pdf",
        "size": "4871732",
        "type": "application/pdf",
        "pages_count": 510,
        "thumbnail": {
            "image_data": "<base64-encoded-thumbnail>",
            "dimensions": {
                "width": 740,
                "height": 1109
            }
        },
        "url": "$udsLink",
        "comment": "download here",
        "dimensions": {
            "height": 720,
            "width": 1280
        }
    },
    "user": {
        "name": "Ryan West",
        "id": "970123457"
    },
    "type": "file",
    "ack_key": "1763107281836"
}

Sticker

Triggered when a business receives a sticker from a customer.


{
    "content": {
        "type": "custom",
        "url": "$udsLink",
        "user": {
            "id": "970123457",
            "name": "Ryan"
        }
    },
    "user": {
        "name": "Ryan West",
        "id": "970123457"
    },
    "type": "sticker",
    "ack_key": "1763107281836"
}

For default/system stickers, the payload follows this format instead:


{
    "content": {
        "type": "default",
        "emoji": "🤔",
        "unicode": "U+1F914",
        "id": ":cat05_Cat:",
        "name": "05_Cat",
        "alias": "Thinking face",
        "pack": "cat",
        "static": false
    },
    "user": {
        "name": "Ryan West",
        "id": "970123457"
    },
    "type": "sticker",
    "ack_key": "1763107281836"
}