Documentation

Webhooks

Webhooks are how WhatSyncs tells your systems that something happened. They are signed, retried on failure, and every attempt is recorded.

Event types

Event	Fires when
`whatsapp.message.received`	An inbound message arrived on a connected number.
`whatsapp.message.sent`	An outbound message was sent from a connected number.
`whatsapp.message.status`	Delivery or read status changed for a message.
`whatsapp.media.synced`	Media attached to a message finished synchronizing.
`whatsapp.history.synced`	A batch of available conversation history was synchronized.
`connection.connected`	A WhatsApp session linked successfully.
`connection.syncing`	A session is catching up after linking or reconnecting.
`connection.reconnecting`	A session dropped and is being restored.
`connection.disconnected`	A session is no longer linked and needs attention.

Payload envelope

Every payload carries an event name, a unique event id, a creation timestamp and the connection it relates to. Resource-specific fields sit alongside those.

whatsapp.message.status

signed

     {          "event"  :     "whatsapp.message.status"  ,          "id"  :     "evt_01H9X2N4R1WW07"  ,          "message"  :     {     "id"  :     "msg_3EB0C9D1A7F2"     }  ,          "status"  :     "read"  ,          "timestamp"  :     "2026-03-04T09:44:51Z"      }

Signature verification

The signature header contains a timestamp and an HMAC-SHA256 digest computed over timestamp + "." + rawBody using your signing secret.

verify-signature.js

     import   crypto   from     "node:crypto"  ;           // Verify that an event really came from WhatSyncs before acting on it.      export     function     verifySignature  (  rawBody  ,   header  ,   secret  )     {          const     [  timestamp  ,   signature  ]     =   header  .  split  (  ","  )  ;          const   payload   =   timestamp   +     "."     +   rawBody  ;          const   expected   =   crypto            .  createHmac  (  "sha256"  ,   secret  )            .  update  (  payload  )            .  digest  (  "hex"  )  ;               const   a   =   Buffer  .  from  (  signature  )  ;          const   b   =   Buffer  .  from  (  expected  )  ;          if     (  a  .  length   !  =  =   b  .  length  )     return     false  ;          return   crypto  .  timingSafeEqual  (  a  ,   b  )  ;      }

Verify against the raw body, before any JSON parsing.
Reject timestamps outside a tolerance window to prevent replay.
Compare digests in constant time.

Retries

A delivery is successful when your endpoint returns a 2xx within the timeout. Anything else — a 5xx, a connection failure, a timeout — is retried on an increasing backoff schedule.

Delivery logs

Every attempt is recorded with the status code your endpoint returned and how long it took, which turns "the integration is broken" into a question with an answer.

GET /webhooks/deliveries

200 OK

     curl     "https://api.whatsyncs.com/v1/webhooks/deliveries?status=failed&limit=50"     \          -H     "Authorization: Bearer YOUR_API_KEY"

Everything on this page works on the Free plan, including webhooks and full API access.

Start Free

Event types

Event	Fires when
`whatsapp.message.received`	An inbound message arrived on a connected number.
`whatsapp.message.sent`	An outbound message was sent from a connected number.
`whatsapp.message.status`	Delivery or read status changed for a message.
`whatsapp.media.synced`	Media attached to a message finished synchronizing.
`whatsapp.history.synced`	A batch of available conversation history was synchronized.
`connection.connected`	A WhatsApp session linked successfully.
`connection.syncing`	A session is catching up after linking or reconnecting.
`connection.reconnecting`	A session dropped and is being restored.
`connection.disconnected`	A session is no longer linked and needs attention.

Payload envelope

Every payload carries an event name, a unique event id, a creation timestamp and the connection it relates to. Resource-specific fields sit alongside those.

whatsapp.message.status

signed

     {          "event"  :     "whatsapp.message.status"  ,          "id"  :     "evt_01H9X2N4R1WW07"  ,          "message"  :     {     "id"  :     "msg_3EB0C9D1A7F2"     }  ,          "status"  :     "read"  ,          "timestamp"  :     "2026-03-04T09:44:51Z"      }

Signature verification

The signature header contains a timestamp and an HMAC-SHA256 digest computed over timestamp + "." + rawBody using your signing secret.

verify-signature.js

     import   crypto   from     "node:crypto"  ;           // Verify that an event really came from WhatSyncs before acting on it.      export     function     verifySignature  (  rawBody  ,   header  ,   secret  )     {          const     [  timestamp  ,   signature  ]     =   header  .  split  (  ","  )  ;          const   payload   =   timestamp   +     "."     +   rawBody  ;          const   expected   =   crypto            .  createHmac  (  "sha256"  ,   secret  )            .  update  (  payload  )            .  digest  (  "hex"  )  ;               const   a   =   Buffer  .  from  (  signature  )  ;          const   b   =   Buffer  .  from  (  expected  )  ;          if     (  a  .  length   !  =  =   b  .  length  )     return     false  ;          return   crypto  .  timingSafeEqual  (  a  ,   b  )  ;      }

Verify against the raw body, before any JSON parsing.

Reject timestamps outside a tolerance window to prevent replay.

Compare digests in constant time.

Delivery logs

Every attempt is recorded with the status code your endpoint returned and how long it took, which turns "the integration is broken" into a question with an answer.

GET /webhooks/deliveries

200 OK

     curl     "https://api.whatsyncs.com/v1/webhooks/deliveries?status=failed&limit=50"     \          -H     "Authorization: Bearer YOUR_API_KEY"