Events
Every event is a JSON object with the same three fields:
| Field | Description |
|---|---|
type | The event type, for example message.received |
timestamp | When the event happened, in UTC (ISO 8601) |
data | The payload. Its shape depends on the type |
Request headers
| Header | Description |
|---|---|
webhook-id | The ID of the event. It stays the same across retries |
webhook-timestamp | When Volt sent this attempt, in seconds since 1970 |
webhook-signature | The signature of the request. See Verify Signatures |
content-type | application/json |
user-agent | Volt-Webhooks/1 |
message.received
Someone sent a message to your line, in a direct chat or in a group.
{
"type": "message.received",
"timestamp": "2026-11-15T14:31:03Z",
"data": {
"id": "3EB0C4A1F29E77D01B",
"chat": {
"id": "5491155550101@s.whatsapp.net",
"is_group": false
},
"sender": {
"id": "5491155550101@s.whatsapp.net",
"name": "Ana"
},
"from_me": false,
"text": "Hi, is the order ready?",
"sent_at": "2026-11-15T14:31:03Z"
}
}message.sent
Your line sent a message. The payload has the same fields, and from_me is true.
Message fields
| Field | Description |
|---|---|
id | The WhatsApp ID of the message |
chat.id | The chat. A group ends in @g.us. A direct chat ends in @s.whatsapp.net (a phone number) or in @lid (a WhatsApp ID without a phone number) |
chat.is_group | true for a group |
sender.id | Who sent the message, in the same forms as a direct chat ID |
sender.name | The name of the sender, when Volt knows it |
from_me | true when your line sent the message |
text | The text of the message, or the caption of a file. Absent when there is none |
media | Present when the message has a file: type (for example image or audio) and mime_type. The file itself is not in the event |
quoted_message_id | The ID of the message this one replies to. Absent when it is not a reply |
sent_at | When the message was sent, in UTC |
To get a file, use the get-message-media tool of the MCP server with the message ID.
webhook.test
Volt sends this event when you add an endpoint and when you click Send test. You cannot subscribe to it, and it does not count against your plan.
{
"type": "webhook.test",
"timestamp": "2026-11-15T14:28:01Z",
"data": {
"message": "Volt can reach this endpoint."
}
}Delivery
- Repeats are possible. Volt retries an event until your server answers
2xx, so the same event can arrive more than once. Usewebhook-idto drop repeats. - Not a complete log. In rare cases, such as an outage on our side at the moment a message arrives, an event is not sent at all. Volt does not replay it. If you need every message, read the chat through the MCP server as well.
- No guaranteed order. Use
sent_atto order messages. - Live messages only. Volt sends the messages that arrive after you add the endpoint. It does not send your history.
Retries
An attempt succeeds when your server answers 2xx in less than 10 seconds. If it does not, Volt tries again:
| Attempt | Wait after the last attempt |
|---|---|
| 2 | 5 seconds |
| 3 | 5 minutes |
| 4 | 30 minutes |
| 5 | 2 hours |
| 6 | 5 hours |
| 7 | 10 hours |
| 8 | 6 hours |
After the eighth attempt, Volt drops the event.
When three attempts of one event fail in a row, Volt sends you one WhatsApp message with the host of the endpoint. If the endpoint recovers and fails again, Volt does not send a second alert for a failure that starts on the same day (UTC).