WhatsApp Webhook Documentation

Product Information

Author: Alejandro J. Elías

Company: DeveloperTeam Software Solutions

Version: 02.5

Modified: Aug 20, 2025

Website: www.developerteam.com.ar

Overview
Endpoint Configuration
Message Notifications
Status Tracking
Best Practices
Testing & Examples

Important Note

This webhook documentation is designed for defensive security purposes only. It should be used for legitimate business communications, notification handling, and customer service applications.

Descripción General

Guía de integración para recibir el evento de mensaje y las notificaciones de estado: sent → delivered → viewed.

El sistema de webhooks de WhatsApp permite recibir notificaciones en tiempo real sobre mensajes enviados y recibidos, así como actualizaciones del estado de entrega.

1) Configuración del Endpoint

Especificaciones del Endpoint

Método HTTP: POST

Content-Type: application/json; charset=utf-8

Respuesta recomendada: 200 OK (procesar asíncronamente, no bloquear)

Consejo: loguear siempre GUID, GUIDUSER/GUIDUSUARIO e ID para correlacionar la notificación inicial con los cambios de estado.

2) Notificación Inicial de Mensaje

Estructura del Payload

{
  "Notifications": {
    "AnswerG": {
      "GUID": "XXXXXXXXXXXXXXX1",
      "GUIDUSUARIO": "XXXXXXXXXXXXXXX2",
      "FECHA": 82027,
      "HORA": 4173101,
      "ID": "XXXXXXXXXXXXXXXXXXXXXXX3",
      "FROMME": "1",
      "PUSHNAME": "Demo User",
      "PHONE": "5490000000000",
      "MESSAGE": "Example message",
      "RECEIVER": "5491111111111",
      "GROUPID": "5490000000000@s.whatsapp.net",
      "GROUPSUBJECT": "",
      "ACTION": "Sent",
      "STATUS": "sent",
      "TYPE": "chat",
      "LOG": "",
      "READED": 0,
      "IMAGE": 0,
      "URLIMAGE": "",
      "LOCALPATHIMAGE": "",
      "CODIGOREQUEST": 0,
      "TIMESTAMPOWN": 1753713331462,
      "TIMESTAMPNOTIFICATION": 1753713331,
      "ts": 0,
      "sts": 0,
      "dts": 0,
      "EXTERNALREFERENCE": "",
      "FILENAMECAPTION": "",
      "SUBGROUP": "",
      "RETRIES": 0,
      "GUIDUSER": "XXXXXXXXXXXXXXX2",
      "DATE": "2025-07-28",
      "TIME": "00:13:40"
    },
    "BASE64ENCODE": "RXhhbXBsZSBtZXNzYWdl"
  }
}

Nota: BASE64ENCODE decodifica a "Example message".

Campos Principales

Campo	Tipo	Descripción
`GUID`	string	ID único del evento/mensaje. Útil para idempotencia.
`GUIDUSUARIO`/`GUIDUSER`	string	Identificador del tenant/usuario.
`ID`	string	ID del mensaje; se repite en TrackingStatus.
`FROMME`	"1"/"0"	`1`: saliente; `0`: entrante.
`PHONE` / `RECEIVER`	string	Remitente / destinatario (MSISDN).
`GROUPID`	string	Identificador JID: `@s.whatsapp.net` para números individuales (ej: `5493515115656@s.whatsapp.net`), `@g.us` para grupos (ej: `120363197780292628@g.us`).
`TYPE`	string	Tipo de mensaje (p. ej., `chat`, `image`).
`MESSAGE`	string	Texto del mensaje (si aplica).
`IMAGE`, `URLIMAGE`, `LOCALPATHIMAGE`	num/string	Indicadores/rutas para media.
`ACTION`	string	Tipo de acción: `Sent` (mensaje enviado) o `Received` (mensaje recibido).
`STATUS`	string	Estado de entrega del mensaje: `sent`, `delivered`, `viewed`, `failed`, etc.
`TIMESTAMPOWN`	number	Epoch en ms del evento del sistema.
`TIMESTAMPNOTIFICATION`	number	Epoch en s de la notificación.
`DATE` / `TIME`	string	Fecha/hora legibles.
`FECHA` / `HORA`	number	Representación interna; preferir `DATE`/`TIME` o timestamps para integraciones.
`EXTERNALREFERENCE`	string	Correlación externa (opcional).

3) Seguimiento de Estados (`TrackingStatus`)

Después del webhook inicial, llegan nuevos POST con TrackingStatus.AnswerG, usando el mismo ID para correlación.

Secuencia Típica de Estados

sent: el servidor aceptó el mensaje

delivered: llegó al dispositivo del destinatario

viewed: el destinatario abrió/vio el mensaje

Ejemplos de Payload de Estado

{ "TrackingStatus": { "AnswerG": {
  "GUID": "XXXXXXXXXXXXXXX1",
  "GUIDUSER": "XXXXXXXXXXXXXXX2",
  "ID": "XXXXXXXXXXXXXXXXXXXXXXX3",
  "PHONE": "5490000000000",
  "RECEIVER": "5491111111111",
  "STATUS": "Sent",
  "NOTE": ""
}}}

{ "TrackingStatus": { "AnswerG": {
  "GUID": "XXXXXXXXXXXXXXX1",
  "GUIDUSER": "XXXXXXXXXXXXXXX2",
  "ID": "XXXXXXXXXXXXXXXXXXXXXXX3",
  "PHONE": "5490000000000",
  "RECEIVER": "5491111111111",
  "STATUS": "delivered",
  "NOTE": ""
}}}

{ "TrackingStatus": { "AnswerG": {
  "GUID": "XXXXXXXXXXXXXXX1",
  "GUIDUSER": "XXXXXXXXXXXXXXX2",
  "ID": "XXXXXXXXXXXXXXXXXXXXXXX3",
  "PHONE": "5490000000000",
  "RECEIVER": "5491111111111",
  "STATUS": "viewed",
  "NOTE": ""
}}}

Campos en `TrackingStatus`

Campo	Tipo	Descripción
`GUID` / `GUIDUSER`	string	Correlación y tenant/usuario.
`ID`	string	El mismo ID del mensaje inicial.
`STATUS`	string	`sent`, `delivered` o `viewed`.
`NOTE`	string	Detalle adicional (opcional).
`PHONE` / `RECEIVER`	string	Referencia de remitente/destinatario.

4) Mejores Prácticas

Recomendaciones de Implementación

Idempotencia: usar GUID/ID para no duplicar.
Responder rápido: devolver 200 OK y procesar en background.
Trazabilidad: guardar TIMESTAMPOWN (ms) y TIMESTAMPNOTIFICATION (s).
Contenido: si hay issues de codificación, decodificar BASE64ENCODE.
Grupos: si GROUPID termina en @g.us es un grupo (considerar GROUPSUBJECT/SUBGROUP); si termina en @s.whatsapp.net es un número individual.

5) Pruebas y Ejemplos

Prueba rápida con cURL - Notificación de Mensaje

curl -X POST https://tu-servidor.com/webhook \
  -H "Content-Type: application/json" \
  -d '{ "Notifications": { "AnswerG":
        { "GUID":"g1","GUIDUSUARIO":"u1","ID":"m1","FROMME":"1",
          "PHONE":"5490000000000","RECEIVER":"5491111111111",
          "MESSAGE":"Hola","TYPE":"chat","ACTION":"Sent","STATUS":"sent",
          "TIMESTAMPOWN":1753713331462,"TIMESTAMPNOTIFICATION":1753713331,
          "DATE":"2025-07-28","TIME":"00:13:40" },
        "BASE64ENCODE":"SG9sYQ=="
      }}'

Prueba rápida con cURL - TrackingStatus

# Ejemplo de estado "delivered"
curl -X POST https://tu-servidor.com/webhook \
  -H "Content-Type: application/json" \
  -d '{ "TrackingStatus": { "AnswerG":
        { "GUID":"g1","GUIDUSER":"u1","ID":"m1",
          "PHONE":"5490000000000","RECEIVER":"5491111111111",
          "STATUS":"delivered","NOTE":"" }
      }}'

# Ejemplo de estado "viewed"
curl -X POST https://tu-servidor.com/webhook \
  -H "Content-Type: application/json" \
  -d '{ "TrackingStatus": { "AnswerG":
        { "GUID":"g1","GUIDUSER":"u1","ID":"m1",
          "PHONE":"5490000000000","RECEIVER":"5491111111111",
          "STATUS":"viewed","NOTE":"" }
      }}'

Resumen: recibís una notificación inicial de mensaje y luego webhooks de TrackingStatus con el mismo ID para actualizar Sent → delivered → viewed.

Overview

Integration guide to receive the initial message event and state updates: sent → delivered → viewed.

The WhatsApp webhook system allows you to receive real-time notifications about sent and received messages, as well as delivery status updates.

1) Endpoint Configuration

Endpoint Specifications

HTTP Method: POST

Content-Type: application/json; charset=utf-8

Recommended response: 200 OK (process asynchronously)

Tip: always log GUID, GUIDUSER/GUIDUSUARIO, and ID to correlate the initial notification with subsequent status updates.

2) Initial Message Notification

Payload Structure

{
  "Notifications": {
    "AnswerG": {
      "GUID": "XXXXXXXXXXXXXXX1",
      "GUIDUSUARIO": "XXXXXXXXXXXXXXX2",
      "FECHA": 82027,
      "HORA": 4173101,
      "ID": "XXXXXXXXXXXXXXXXXXXXXXX3",
      "FROMME": "1",
      "PUSHNAME": "Demo User",
      "PHONE": "5490000000000",
      "MESSAGE": "Example message",
      "RECEIVER": "5491111111111",
      "GROUPID": "5490000000000@s.whatsapp.net",
      "GROUPSUBJECT": "",
      "ACTION": "Sent",
      "STATUS": "sent",
      "TYPE": "chat",
      "LOG": "",
      "READED": 0,
      "IMAGE": 0,
      "URLIMAGE": "",
      "LOCALPATHIMAGE": "",
      "CODIGOREQUEST": 0,
      "TIMESTAMPOWN": 1753713331462,
      "TIMESTAMPNOTIFICATION": 1753713331,
      "ts": 0,
      "sts": 0,
      "dts": 0,
      "EXTERNALREFERENCE": "",
      "FILENAMECAPTION": "",
      "SUBGROUP": "",
      "RETRIES": 0,
      "GUIDUSER": "XXXXXXXXXXXXXXX2",
      "DATE": "2025-07-28",
      "TIME": "00:13:40"
    },
    "BASE64ENCODE": "RXhhbXBsZSBtZXNzYWdl"
  }
}

Note: BASE64ENCODE decodes to "Example message".

Key Fields

Field	Type	Description
`GUID`	string	Unique event/message ID. Useful for idempotency.
`GUIDUSUARIO`/`GUIDUSER`	string	Tenant/user identifier.
`ID`	string	Message ID; reused in TrackingStatus.
`FROMME`	"1"/"0"	`1`: outgoing; `0`: incoming.
`PHONE` / `RECEIVER`	string	Sender / recipient (MSISDN).
`GROUPID`	string	WhatsApp JID identifier: `@s.whatsapp.net` for individual numbers (e.g., `5493515115656@s.whatsapp.net`), `@g.us` for groups (e.g., `120363197780292628@g.us`).
`TYPE`	string	Message type (e.g., `chat`, `image`).
`MESSAGE`	string	Text content (if any).
`IMAGE`, `URLIMAGE`, `LOCALPATHIMAGE`	num/string	Media flags/paths.
`ACTION`	string	Action type: `Sent` (outgoing message) or `Received` (incoming message).
`STATUS`	string	Message delivery status: `sent`, `delivered`, `viewed`, `failed`, etc.
`TIMESTAMPOWN`	number	Epoch in ms at system side.
`TIMESTAMPNOTIFICATION`	number	Epoch in s when the notification was generated.
`DATE` / `TIME`	string	Human-readable date/time.
`FECHA` / `HORA`	number	Internal representation; prefer `DATE`/`TIME` or timestamps.
`EXTERNALREFERENCE`	string	Optional external correlation.

3) Status Tracking (`TrackingStatus`)

After the initial webhook, additional POST requests arrive with TrackingStatus.AnswerG, using the same ID for correlation.

Typical Status Sequence

Sent: message accepted by the server

delivered: reached recipient's device

viewed: recipient opened/viewed it

Sample Status Payloads

{ "TrackingStatus": { "AnswerG": {
  "GUID": "XXXXXXXXXXXXXXX1",
  "GUIDUSER": "XXXXXXXXXXXXXXX2",
  "ID": "XXXXXXXXXXXXXXXXXXXXXXX3",
  "PHONE": "5490000000000",
  "RECEIVER": "5491111111111",
  "STATUS": "Sent",
  "NOTE": ""
}}}

{ "TrackingStatus": { "AnswerG": {
  "GUID": "XXXXXXXXXXXXXXX1",
  "GUIDUSER": "XXXXXXXXXXXXXXX2",
  "ID": "XXXXXXXXXXXXXXXXXXXXXXX3",
  "PHONE": "5490000000000",
  "RECEIVER": "5491111111111",
  "STATUS": "delivered",
  "NOTE": ""
}}}

{ "TrackingStatus": { "AnswerG": {
  "GUID": "XXXXXXXXXXXXXXX1",
  "GUIDUSER": "XXXXXXXXXXXXXXX2",
  "ID": "XXXXXXXXXXXXXXXXXXXXXXX3",
  "PHONE": "5490000000000",
  "RECEIVER": "5491111111111",
  "STATUS": "viewed",
  "NOTE": ""
}}}

Fields in `TrackingStatus`

Field	Type	Description
`GUID` / `GUIDUSER`	string	Correlation and tenant/user.
`ID`	string	Same ID as the initial message.
`STATUS`	string	`Sent`, `delivered`, or `viewed`.
`NOTE`	string	Optional additional info.
`PHONE` / `RECEIVER`	string	Sender/recipient reference.

4) Best Practices

Implementation Recommendations

Idempotency: use GUID/ID to avoid duplicates.
Fast response: return 200 OK and process in the background.
Traceability: store TIMESTAMPOWN (ms) and TIMESTAMPNOTIFICATION (s).
Content handling: decode BASE64ENCODE when character encoding is an issue.
Groups: if GROUPID ends with @g.us it's a group (consider GROUPSUBJECT/SUBGROUP); if it ends with @s.whatsapp.net it's an individual number.

5) Testing & Examples

Quick test with cURL - Message Notification

curl -X POST https://your-server.com/webhook \
  -H "Content-Type: application/json" \
  -d '{ "Notifications": { "AnswerG":
        { "GUID":"g1","GUIDUSUARIO":"u1","ID":"m1","FROMME":"1",
          "PHONE":"5490000000000","RECEIVER":"5491111111111",
          "MESSAGE":"Hello","TYPE":"chat","ACTION":"Sent","STATUS":"sent",
          "TIMESTAMPOWN":1753713331462,"TIMESTAMPNOTIFICATION":1753713331,
          "DATE":"2025-07-28","TIME":"00:13:40" },
        "BASE64ENCODE":"SGVsbG8="
      }}'

Quick test with cURL - TrackingStatus

# Example for "delivered" status
curl -X POST https://your-server.com/webhook \
  -H "Content-Type: application/json" \
  -d '{ "TrackingStatus": { "AnswerG":
        { "GUID":"g1","GUIDUSER":"u1","ID":"m1",
          "PHONE":"5490000000000","RECEIVER":"5491111111111",
          "STATUS":"delivered","NOTE":"" }
      }}'

# Example for "viewed" status
curl -X POST https://your-server.com/webhook \
  -H "Content-Type: application/json" \
  -d '{ "TrackingStatus": { "AnswerG":
        { "GUID":"g1","GUIDUSER":"u1","ID":"m1",
          "PHONE":"5490000000000","RECEIVER":"5491111111111",
          "STATUS":"viewed","NOTE":"" }
      }}'

Summary: you receive an initial message notification and then TrackingStatus webhooks with the same ID to update Sent → delivered → viewed.

Documentation generated for WhatsApp Webhook Template v2.5 by Alejandro J. Elías - DeveloperTeam Software Solutions

WhatsApp Webhook Documentation

Table of Contents

Descripción General

1) Configuración del Endpoint

2) Notificación Inicial de Mensaje

Estructura del Payload

Campos Principales

3) Seguimiento de Estados (TrackingStatus)

Ejemplos de Payload de Estado

Campos en TrackingStatus

4) Mejores Prácticas

5) Pruebas y Ejemplos

Overview

1) Endpoint Configuration

2) Initial Message Notification

Payload Structure

Key Fields

3) Status Tracking (TrackingStatus)

Sample Status Payloads

Fields in TrackingStatus

4) Best Practices

5) Testing & Examples

3) Seguimiento de Estados (`TrackingStatus`)

Campos en `TrackingStatus`

3) Status Tracking (`TrackingStatus`)

Fields in `TrackingStatus`