Documentation

Receive messages

Incoming messages reach your systems as webhook events within seconds of arriving. This page walks through a production-shaped handler.

1. Register an endpoint

Register an HTTPS URL you control and choose the events to subscribe to. WhatSyncs posts a JSON body and a signature header to that URL.

whatsapp.message.received

signed

     {          "event"  :     "whatsapp.message.received"  ,          "id"  :     "evt_01H9X2K7Q4ZB3M"  ,          "created_at"  :     "2026-03-04T09:41:07Z"  ,          "connection"  :     {            "id"  :     "conn_sales"  ,            "name"  :     "Sales"  ,            "phone"  :     "+971 4 000 0001"  ,            "status"  :     "healthy"          }  ,          "message"  :     {            "id"  :     "msg_3EB0C9D1A7F2"  ,            "direction"  :     "incoming"  ,            "type"  :     "text"  ,            "text"  :     "I'm interested in the property"  ,            "timestamp"  :     "2026-03-04T09:41:06Z"  ,            "chat"  :     {              "id"  :     "chat_971500000000"  ,              "name"  :     "Amira Khan"  ,              "phone"  :     "+971500000000"            }          }      }

2. Verify the signature

Compute the HMAC over the timestamp and the raw request body. Verify before parsing: a re-serialized JSON body produces a different signature.

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  )  ;      }

3. Acknowledge quickly

Return a 2xx as soon as the event is durably accepted, then do the real work out of band. A handler that calls your CRM synchronously will eventually time out, and a timeout is treated as a failed delivery — which means a retry.

webhook-handler.js

     app  .  post  (  "/webhooks/whatsyncs"  ,     async     (  req  ,   res  )     =  >     {          if     (  !  verifySignature  (  req  .  rawBody  ,   req  .  get  (  "X-WhatSyncs-Signature"  )  ,   SECRET  )  )     {            return   res  .  sendStatus  (  401  )  ;          }               // Acknowledge fast, then process out of band. WhatSyncs retries on timeout,          // so slow handlers cause duplicate deliveries rather than lost events.        res  .  sendStatus  (  200  )  ;               const   event   =   req  .  body  ;          const   key   =   req  .  get  (  "X-WhatSyncs-Idempotency-Key"  )  ;          if     (  await     seenBefore  (  key  )  )     return  ;               await   queue  .  publish  (  "whatsapp-events"  ,     {   key  ,   event   }  )  ;      }  )  ;

4. Deduplicate

Every delivery carries an idempotency key, and every message carries a stable identifier. Record the key before processing and treat a repeat as an update rather than an insert.

5. Handle connection events

Subscribe to connection events so a dropped session raises an alert in the same place as your other integration failures.

connection.disconnected

signed

     {          "event"  :     "connection.disconnected"  ,          "id"  :     "evt_01H9X3B4C5DD90"  ,          "created_at"  :     "2026-03-04T14:02:11Z"  ,          "connection"  :     {            "id"  :     "conn_support"  ,            "name"  :     "Support"  ,            "phone"  :     "+971 4 000 0003"  ,            "status"  :     "disconnected"  ,            "last_event_at"  :     "2026-03-04T13:48:02Z"          }  ,          "reason"  :     "session_logged_out"      }

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

Start Free

1. Register an endpoint

Register an HTTPS URL you control and choose the events to subscribe to. WhatSyncs posts a JSON body and a signature header to that URL.

whatsapp.message.received

signed

     {          "event"  :     "whatsapp.message.received"  ,          "id"  :     "evt_01H9X2K7Q4ZB3M"  ,          "created_at"  :     "2026-03-04T09:41:07Z"  ,          "connection"  :     {            "id"  :     "conn_sales"  ,            "name"  :     "Sales"  ,            "phone"  :     "+971 4 000 0001"  ,            "status"  :     "healthy"          }  ,          "message"  :     {            "id"  :     "msg_3EB0C9D1A7F2"  ,            "direction"  :     "incoming"  ,            "type"  :     "text"  ,            "text"  :     "I'm interested in the property"  ,            "timestamp"  :     "2026-03-04T09:41:06Z"  ,            "chat"  :     {              "id"  :     "chat_971500000000"  ,              "name"  :     "Amira Khan"  ,              "phone"  :     "+971500000000"            }          }      }

2. Verify the signature

Compute the HMAC over the timestamp and the raw request body. Verify before parsing: a re-serialized JSON body produces a different signature.

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  )  ;      }

3. Acknowledge quickly

webhook-handler.js

     app  .  post  (  "/webhooks/whatsyncs"  ,     async     (  req  ,   res  )     =  >     {          if     (  !  verifySignature  (  req  .  rawBody  ,   req  .  get  (  "X-WhatSyncs-Signature"  )  ,   SECRET  )  )     {            return   res  .  sendStatus  (  401  )  ;          }               // Acknowledge fast, then process out of band. WhatSyncs retries on timeout,          // so slow handlers cause duplicate deliveries rather than lost events.        res  .  sendStatus  (  200  )  ;               const   event   =   req  .  body  ;          const   key   =   req  .  get  (  "X-WhatSyncs-Idempotency-Key"  )  ;          if     (  await     seenBefore  (  key  )  )     return  ;               await   queue  .  publish  (  "whatsapp-events"  ,     {   key  ,   event   }  )  ;      }  )  ;

5. Handle connection events

Subscribe to connection events so a dropped session raises an alert in the same place as your other integration failures.

connection.disconnected

signed

     {          "event"  :     "connection.disconnected"  ,          "id"  :     "evt_01H9X3B4C5DD90"  ,          "created_at"  :     "2026-03-04T14:02:11Z"  ,          "connection"  :     {            "id"  :     "conn_support"  ,            "name"  :     "Support"  ,            "phone"  :     "+971 4 000 0003"  ,            "status"  :     "disconnected"  ,            "last_event_at"  :     "2026-03-04T13:48:02Z"          }  ,          "reason"  :     "session_logged_out"      }