Webhooks
What are Webhooks
A webhook is a mechanism that allows your application to receive automatic webhooks about events occurring in the MassAccess system. When an event happens — a message status changes, a client phone number is updated, or a client interacts with your bot — MassAccess sends an HTTP POST request to your server with event data in JSON format.
Requests are sent to the Webhook URL configured in your company dashboard (Settings → Webhook URL). Each request includes an HMAC-SHA256 signature (X-Signature header) so you can verify its authenticity.
How to Set Up Webhooks
To start receiving webhooks, log in to your company dashboard, go to Settings, and specify your server URL in the «Webhook URL» field. After saving, MassAccess will begin sending HTTP POST requests to this URL for every event in your company. No additional API calls are needed — webhooks are sent automatically for all message status changes, phone number updates, and client interactions with your bots.
The Check button sends one signed test request with event = webhook.test and data.test = true. It carries the same application delivery headers as business events: X-Signature, Idempotency-Key, and X-Webhook-Attempt. The address is considered available when the server returns HTTP 2xx; 4xx means the server is reachable but rejected the request, while 5xx, timeout, or a network error means the endpoint is unavailable. The check confirms only that the safe webhook.test event is accepted; it does not guarantee acceptance of every event type. Use real delivery or /api/v1/webhooks/replay for a complete check.
Event Types
MassAccess sends webhooks for the following events:
| Event | Description |
|---|---|
| message.status | Sent when a message reaches a terminal status: sent or failed. The data.state field contains the current status. If data.state is "failed", additional data.error_code and data.error_description fields are included. |
| client.phone.changed | Sent when a client's phone number is changed via the /api/v1/change_phone endpoint. The data.state field is "completed" on success. If the change fails, data.state is "failed" with error_code and error_description fields. |
| client.check | Sent for /api/v1/client/check. data.exists indicates whether the client has an active company registration, and data.bots contains the corresponding bots. |
| client.registered | Sent when a new client registers through your bot in a messenger and when a client reconnects to the bot. The payload includes phone, bot_name, and service fields. |
| message.inbound | A text message received from a confirmed client in a private Telegram or MAX dialog. Commands, contacts, callbacks, status/service events and attachments are excluded. |