Skip to main content
GOWA POSTs a JSON document to your URL for every WhatsApp event it receives: messages, receipts, reactions, edits, deletions, typing indicators, group changes, labels, newsletters and calls. There is no webhook registration endpoint. Configure webhooks at startup, or per device through /devices/{device_id}/webhook.

How delivery works

Each target URL is delivered independently, with its own secret and retries.

Configure

Equivalent flags: --webhook, --webhook-secret, --webhook-events, --webhook-ignore-jids, --webhook-insecure-skip-verify, and --webhook-all-device-receipts. Set a private signing key explicitly. An unset key or the old published value secret causes GOWA to generate a random key that changes on restart and log a warning. Receivers need an explicit shared key to verify signatures across restarts. HTTPS certificates are verified by default.

Events

Event names in the allowlist are case-insensitive.

Payload

Every request has the same envelope:
Replies add replied_to_id and quoted_body. Receipts use ids (array) and receipt_type. Group participant events carry chat_id, type, and jids. Group name changes use a separate group.info shape. sender_display_name appears only when from is a non-empty string. For another sender, GOWA prefers the saved contact name, live event push name, stored push name, business name, then the JID user part. For the active account, it prefers the account push name, then its JID identity. Resolution is best-effort. The legacy from_name remains the message event push name. Incoming messages may include is_business: true, verified_name, and verified_level when WhatsApp supplies a verified-name certificate. These fields are omitted otherwise. Absence does not establish whether a sender is a business, and verified_level is the raw upstream value rather than a guarantee of an official badge.

Media

With WHATSAPP_AUTO_DOWNLOAD_MEDIA=true (default), media is saved under statics/media/ and the media field holds the path:
When a caption is present, the field becomes {"path": "...", "caption": "..."} and the caption is also in body. With auto-download off, it is {"url": "https://mmg.whatsapp.net/...", "caption": "..."}; fetch the file later with GET /message/{message_id}/download?phone=<chat>. The full catalogue of payloads (polls, locations, contacts, view-once, ads referrals and more) is in the upstream webhook payload reference.

Albums and structured messages

An album arrives as several message events. The header has no message body and carries the expected item counts:
Each photo or video arrives in its own normal media event with album_id: "ALBUM_HEADER_ID". Group items by that ID. The header is not a downloadable media item and is not forwarded to Chatwoot. Poll creation, votes, edits, and added options also use message. Inspect the structured poll object rather than relying on body. Option hashes are lowercase hexadecimal SHA-256 hashes of exact option names. Existing WHATSAPP_WEBHOOK_EVENTS=message subscriptions receive these interactions.

Online and offline presence

Subscribe for each individual contact using the same device that receives the events:
A successful response contains results.subscribed: true and results.jid. Group and newsletter JIDs are rejected. A subscription does not override your device’s presence setting. For continuous updates, start GOWA with:
The default presence pulse ends by marking the device unavailable, which stops contact presence updates. Marking the device available suppresses WhatsApp push notifications on the phone while it runs. Account for this trade-off before enabling continuous tracking.
state is available or unavailable. last_seen is omitted when unknown or hidden by the contact’s privacy settings. from_lid is included when applicable. Typing and recording remain separate chat_presence events and do not use this subscription.

Group name changes

name_set_by is resolved from LID to phone JID when possible and omitted when WhatsApp does not identify the actor. Subscribe to group.info explicitly if your event allowlist excludes other events.

Newsletter counter updates

newsletter.message reports live counters rather than a guaranteed new-post body. Entries always include server_id. message_id, type, and timestamp are omitted when WhatsApp does not supply them. Zero or absent counters may be omitted.
When available, reaction_counts contains WhatsApp’s reaction counts. Consume updates by newsletter ID and server ID. Do not treat a missing counter as a reset to zero.

Account restrictions and logout

Device events always carry session_id, so slots using the same WhatsApp number remain distinguishable. The event uses the emitting slot’s webhook configuration. A remote logout keeps the slot for re-pairing and reports the identity from before logout. Slot webhook settings survive re-pairing. These events are not sent to Chatwoot.
Codes are forwarded unchanged and reason text comes from whatsmeow. Unknown codes still arrive. Logout codes 403 and 406 alone do not establish the exact cause. A temporary ban duration of zero means WhatsApp gave no expiry. A reach-out timelock restricts starting new chats and may produce send error 463.

Verify signatures

Each request carries X-Hub-Signature-256: sha256=<hex>, an HMAC-SHA256 of the raw request body keyed with the webhook secret. Compute it over the exact bytes received, before parsing JSON.

Delivery and retries

  • Each attempt times out after 10 seconds.
  • Any non-2xx response or network error is retried. GOWA makes up to 5 attempts, waiting 1 s, 2 s, 4 s, and 8 s between them. The event handler’s context deadline can stop delivery before all attempts complete.
  • After the last failure the event is dropped and logged. There is no persistent queue or dead-letter store.
  • Several URLs are delivered independently.
Respond 2xx after accepting the event into your own durable processing queue. Make handlers idempotent because a retried event can arrive more than once.

Linked-device receipts

By default, GOWA forwards contact acknowledgements from primary devices only to reduce duplicates. The current account’s own read and read-self receipts pass from all its devices. For these own-account receipts, payload.from is the account JID and payload.ids identifies incoming messages that were read. Set WHATSAPP_WEBHOOK_ALL_DEVICE_RECEIPTS=true or --webhook-all-device-receipts=true to receive contact receipts from linked devices too, including when the contact’s phone is offline. The CLI flag overrides the environment, including an explicit false. This opt-in can produce duplicate or out-of-order acknowledgements. Apply updates idempotently per account, chat, and message ID. Never downgrade a read message to delivered when an older receipt arrives. Message IDs and sender JIDs keep their canonical form without device suffixes.

Filter events

By type: WHATSAPP_WEBHOOK_EVENTS=message,message.ack forwards only those events. By chat or sender: WHATSAPP_WEBHOOK_IGNORE_JIDS matches chat_id, from, chat_lid and from_lid. Entries starting with @ are wildcards for a whole address space (@g.us, @s.whatsapp.net, @lid); anything else is an exact JID.
@s.whatsapp.net also matches group messages, because their from is a user JID. Use @g.us to mute groups. The two filters combine: an event is sent only if its type is allowed and its JID is not ignored.

Per-device webhooks

Give a slot its own webhook, secret and event allowlist:
The same fields are accepted by POST /devices. Read the current setting with GET /devices/{device_id}/webhook. Send "webhook_url": "" to clear it. An empty device webhook_secret or webhook_events falls back to the corresponding global setting. The stored device webhook_insecure_skip_verify boolean replaces the global TLS setting. In particular, false keeps certificate verification enabled even when the global bypass is enabled. By default a per-device URL replaces the global WHATSAPP_WEBHOOK for that slot. With WHATSAPP_WEBHOOK_DEVICE_MERGE_GLOBAL=true it is added to the global URLs instead: the device URL uses the device secret and allowlist, the global URLs keep the global ones, and a URL present in both receives the event once. Ignore-JID rules apply to both.

Testing locally

Expose a local receiver with a tunnel (for example ngrok http 8080) and set WHATSAPP_WEBHOOK to the tunnel URL. With --debug=true, GOWA logs each delivery attempt and failure.

Other ways to receive events

  • WebSocket at /ws?device_id=<id> pushes pairing and status events to dashboard clients. Use webhooks for message delivery.
  • Polling: GET /chats and GET /chat/{chat_jid}/messages read GOWA’s local chat storage. See Receiving messages.