Skip to Content
WebhooksEvents

Events

Every event is a JSON object with the same three fields:

FieldDescription
typeThe event type, for example message.received
timestampWhen the event happened, in UTC (ISO 8601)
dataThe payload. Its shape depends on the type

Request headers

HeaderDescription
webhook-idThe ID of the event. It stays the same across retries
webhook-timestampWhen Volt sent this attempt, in seconds since 1970
webhook-signatureThe signature of the request. See Verify Signatures
content-typeapplication/json
user-agentVolt-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

FieldDescription
idThe WhatsApp ID of the message
chat.idThe 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_grouptrue for a group
sender.idWho sent the message, in the same forms as a direct chat ID
sender.nameThe name of the sender, when Volt knows it
from_metrue when your line sent the message
textThe text of the message, or the caption of a file. Absent when there is none
mediaPresent 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_idThe ID of the message this one replies to. Absent when it is not a reply
sent_atWhen 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. Use webhook-id to 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_at to 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:

AttemptWait after the last attempt
25 seconds
35 minutes
430 minutes
52 hours
65 hours
710 hours
86 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).