Webhooks de StackNetic
Te avisamos por HTTPS, al momento y con una firma que puedes comprobar, cuando llega un mensaje a tus números, cuando cambia su estado y cuando pasa algo con tus plantillas o tus números.
En esta página
Qué recibes#
Un POST con content-type: application/json a tu URL cada vez que pasa algo a lo que te suscribiste. Los endpoints se crean en la consola, en Desarrolladores → Webhooks, o desde tu sistema con la API (/v1/webhook-endpoints, con una clave con el permiso webhooks:write), con los eventos y los números que te interesan.
El cuerpo es un sobre con object, id, type, api_version, created_at y data, con los mismos recursos que la API (el mensaje, el número). Las cabeceras siguen el estándar abierto Standard Webhooks, que tiene librerías de verificación para la mayoría de los lenguajes.
| Cabecera | Qué es |
|---|---|
webhook-id | El id del evento (evt_…). Es el mismo en cada reintento y en cada reenvío: úsalo para no procesar dos veces el mismo aviso. |
webhook-timestamp | Cuándo salió este intento, en segundos desde 1970 (UTC). |
webhook-signature | Una o dos firmas v1,… separadas por espacios (dos mientras rotas el secreto). |
stacknetic-event-type | El tipo del evento, para enrutarlo sin leer el cuerpo. |
Una entrega completa
POST /webhooks/stacknetic HTTP/1.1
Host: api.tuempresa.com
content-type: application/json
user-agent: StackNetic-Webhooks/1.0 (+https://messaging.stack-netic.com/docs/webhooks)
stacknetic-event-type: message.received
webhook-id: evt_02y9Hg6I37jaHgkutafuog
webhook-timestamp: 1790547003
webhook-signature: v1,33i9ly2Ss5drK5uMjol2s62jC6DSU2p9qABNwVNfJ9g=
{"object":"event","id":"evt_02y9Hg6I37jaHgkutafuog","type":"message.received","api_version":"v1","created_at":1790547000,"data":{"message":{"object":"message","id":"msg_02y9HflgNTRjaQMubfP6vm","number":{"id":"num_02y8w48sgGf2ztA7qbjqso","phone":"+593969847312"},"contact":{"phone":"+593991234567","user_id":null,"name":"Ana Pérez"},"direction":"inbound","type":"interactive","text":"Confirmar cita","template":null,"media":null,"status":"received","error":null,"client_reference":null,"sent_by":null,"whatsapp_id":"wamid.HBgMNTkzOTkxMjM0NTY3FQIAEhggQTFCMkMzRDRFNUY2","created_at":1790546998,"status_updated_at":1790546998,"expires_at":null,"reply_to":"wamid.HBgMNTkzOTkxMjM0NTY3FQIAERgSMUQ3RjBBMkI2QjZBQTlGNjNBAA==","interactive":{"type":"button_reply","id":"confirmar_cita_8841","title":"Confirmar cita"},"location":null,"reaction":null,"referral":null}}}Verifica la firma, siempre#
- Lee el cuerpo crudo, sin volver a serializarlo.
- Rechaza si
webhook-timestampse aleja más de 5 minutos de tu hora. - Calcula
HMAC-SHA256con la clave (la parte en base64 que sigue awhsec_, decodificada) sobre{webhook-id}.{webhook-timestamp}.{cuerpo}, en base64. - Acepta si coincide, en tiempo constante, con alguna de las firmas
v1,…dewebhook-signature.
import crypto from "node:crypto";
// cuerpo: el texto crudo de la petición (sin volver a serializarlo). h: sus cabeceras.
export function verificarStackNetic(cuerpo, h, secreto, toleranciaSeg = 300) {
const id = h["webhook-id"], ts = h["webhook-timestamp"], firmas = h["webhook-signature"];
if (!id || !ts || !firmas) throw new Error("Faltan las cabeceras de firma");
if (Math.abs(Math.floor(Date.now() / 1000) - Number(ts)) > toleranciaSeg) throw new Error("Marca de tiempo fuera de tolerancia");
const clave = Buffer.from(secreto.replace(/^whsec_/, ""), "base64");
const esperada = crypto.createHmac("sha256", clave).update(`${id}.${ts}.${cuerpo}`).digest();
const valida = firmas.split(" ").some((parte) => {
const [version, firma] = parte.split(",");
if (version !== "v1" || !firma) return false;
const recibida = Buffer.from(firma, "base64");
return recibida.length === esperada.length && crypto.timingSafeEqual(recibida, esperada);
});
if (!valida) throw new Error("Firma no válida");
return JSON.parse(cuerpo);
}import base64, hashlib, hmac, json, time
# cuerpo: los bytes crudos de la petición. h: sus cabeceras.
def verificar_stacknetic(cuerpo: bytes, h: dict, secreto: str, tolerancia: int = 300) -> dict:
id_, ts, firmas = h["webhook-id"], h["webhook-timestamp"], h["webhook-signature"]
if abs(int(time.time()) - int(ts)) > tolerancia:
raise ValueError("Marca de tiempo fuera de tolerancia")
clave = base64.b64decode(secreto.removeprefix("whsec_"))
esperada = base64.b64encode(hmac.new(clave, f"{id_}.{ts}.".encode() + cuerpo, hashlib.sha256).digest()).decode()
for parte in firmas.split(" "):
version, _, firma = parte.partition(",")
if version == "v1" and hmac.compare_digest(firma, esperada):
return json.loads(cuerpo)
raise ValueError("Firma no válida")function verificarStackNetic(string $cuerpo, array $h, string $secreto, int $tolerancia = 300): array {
$id = $h['webhook-id'] ?? ''; $ts = $h['webhook-timestamp'] ?? ''; $firmas = $h['webhook-signature'] ?? '';
if (abs(time() - (int) $ts) > $tolerancia) throw new RuntimeException('Marca de tiempo fuera de tolerancia');
$clave = base64_decode(preg_replace('/^whsec_/', '', $secreto));
$esperada = base64_encode(hash_hmac('sha256', "$id.$ts.$cuerpo", $clave, true));
foreach (explode(' ', $firmas) as $parte) {
[$version, $firma] = array_pad(explode(',', $parte, 2), 2, '');
if ($version === 'v1' && hash_equals($esperada, $firma)) return json_decode($cuerpo, true);
}
throw new RuntimeException('Firma no válida');
}
// El cuerpo crudo: file_get_contents('php://input'). Las cabeceras: $_SERVER['HTTP_WEBHOOK_ID'], etc.Para probar tu código: con el secreto whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw (de ejemplo, no es de nadie), la entrega de arriba verifica. Cambia un carácter del cuerpo y deja de verificar. Su marca de tiempo es antigua: para esta prueba, amplía la tolerancia.
Responde rápido#
Responde 2xx en menos de 15 segundos y procesa después, en una cola tuya. Cualquier otra respuesta, una redirección, un certificado no válido o pasar de 15 s cuenta como fallo y se reintenta. Si ya no quieres avisos en esa URL, responde 410 Gone: desactivamos el endpoint.
Deduplica y no dependas del orden#
- Puede llegarte el mismo aviso más de una vez (reintentos, reenvíos): usa
webhook-idpara no procesarlo dos veces. - Los avisos no llegan en orden. Para los estados de un mensaje, quédate con el más avanzado:
sent<delivered<read.failedes final, salvo que suerror.codesea uno de los que Meta puede desmentir (expired,unknown_outcome,workspace_inactive,channel_unavailable,channel_blocked,internal): entonces unsentposterior manda. - Usa
status_updated_atdel mensaje —la hora del hecho— y no la de llegada.
Reintentos y desactivación#
Si falla, reintentamos durante unas 72 horas: a 1 minuto, 5 minutos, 30 minutos, 2 horas, 5 horas, 10 horas, 10 horas, 12 horas, 12 horas y 20 horas (con un poco de azar). Si tu servidor pide esperar (429 o 503 con Retry-After), lo respetamos hasta una hora. Si un endpoint falla seguido, espaciamos los intentos para no saturarlo y, en cuanto vuelve a responder, enviamos lo que quedó en espera.
Tras 24 horas fallando avisamos por correo a los propietarios y administradores del espacio; a las 72 horas (y al menos 10 intentos) desactivamos el endpoint. Al reactivarlo puedes recuperar lo que falló desde una fecha. El registro de entregas se conserva 30 días.
Los eventos#
Recibes solo los tipos que eliges al crear el endpoint: no hay comodín, así que un tipo nuevo no te llega hasta que lo eliges. Los de mensajes y llamadas llevan datos de tus contactos (su teléfono y su nombre; los de mensajes, también el texto): solo los pueden elegir quienes pueden leer las conversaciones, y por la API, una clave con messages:read. Los de llamadas solo existen en los espacios con llamadas de WhatsApp.
| Tipo | Mensajes | Cuándo |
|---|---|---|
message.received | Mensaje recibido | Un contacto escribe a uno de tus números. |
message.status | Estado de un mensaje | Un mensaje que enviaste se envió, se entregó, se leyó o falló. |
message.echo | Mensaje desde el teléfono | Alguien escribió desde la app WhatsApp Business del número. |
| Tipo | Llamadas | Cuándo |
|---|---|---|
call.ended | Llamada terminada | Terminó una llamada de WhatsApp, entrante o saliente, contestada o no: con su resultado, quién la atendió y cuánto duró. |
| Tipo | Plantillas | Cuándo |
|---|---|---|
template.status | Estado de una plantilla | Meta aprobó, rechazó, pausó o desactivó una plantilla. |
| Tipo | Números | Cuándo |
|---|---|---|
number.connected | Número conectado | Se conectó o se reconectó un número. |
number.disconnected | Número desconectado | Un número dejó de estar conectado. |
number.quality | Calidad del número | Cambió la calidad o el límite de mensajes de un número. |
number.status | Estado del número | Un número pasó a poder o a no poder enviar. |
Las llamadas#
call.ended llega una vez por llamada, cuando termina —entrante o saliente, contestada o no—: no hay avisos mientras suena ni mientras se habla. agent es quien llamó o contestó del equipo (null en una perdida). Para el costo, suma billable_pulses: los pulsos de 6 s que cobra WhatsApp en las salientes contestadas, con la tarifa del país del contacto.
| result | Qué pasó |
|---|---|
completed | Hubo conversación: trae started_at, duration_sec y, si fue saliente, billable_pulses. |
missed | Una entrante que nadie contestó. Desde la consola se puede devolver. |
no_answer | Una saliente que el contacto no contestó. |
declined | El contacto rechazó la saliente. |
canceled | Quien llamaba colgó antes de que contestaran. |
failed | Un error de WhatsApp o de conexión: su código y su título, en error. |
expired | No llegó su final y se cerró sola, pasado su plazo. |
message.received#
Un contacto pulsa un botón de tu mensaje.
{
"object": "event",
"id": "evt_02y9Hg6I37jaHgkutafuog",
"type": "message.received",
"api_version": "v1",
"created_at": 1790547000,
"data": {
"message": {
"object": "message",
"id": "msg_02y9HflgNTRjaQMubfP6vm",
"number": {
"id": "num_02y8w48sgGf2ztA7qbjqso",
"phone": "+593969847312"
},
"contact": {
"phone": "+593991234567",
"user_id": null,
"name": "Ana Pérez"
},
"direction": "inbound",
"type": "interactive",
"text": "Confirmar cita",
"template": null,
"media": null,
"status": "received",
"error": null,
"client_reference": null,
"sent_by": null,
"whatsapp_id": "wamid.HBgMNTkzOTkxMjM0NTY3FQIAEhggQTFCMkMzRDRFNUY2",
"created_at": 1790546998,
"status_updated_at": 1790546998,
"expires_at": null,
"reply_to": "wamid.HBgMNTkzOTkxMjM0NTY3FQIAERgSMUQ3RjBBMkI2QjZBQTlGNjNBAA==",
"interactive": {
"type": "button_reply",
"id": "confirmar_cita_8841",
"title": "Confirmar cita"
},
"location": null,
"reaction": null,
"referral": null
}
}
}message.status#
Un mensaje que enviaste se entregó.
{
"object": "event",
"id": "evt_02y9Hg6I37jaHgkutafuog",
"type": "message.status",
"api_version": "v1",
"created_at": 1790546412,
"data": {
"message": {
"object": "message",
"id": "msg_02y9HflgNTRjaQMubfP6vm",
"number": {
"id": "num_02y8w48sgGf2ztA7qbjqso",
"phone": "+593969847312"
},
"contact": {
"phone": "+593991234567",
"user_id": null,
"name": null
},
"direction": "outbound",
"type": "template",
"text": "Hola Ana, te esperamos el martes 12 de octubre a las 10:00.",
"template": {
"name": "recordatorio_cita",
"language": "es"
},
"media": null,
"status": "delivered",
"error": null,
"client_reference": "cita-8841",
"sent_by": {
"type": "api_key",
"id": "key_02y9HfsYGgsLoqUuhdpNYk",
"name": "Agenda producción"
},
"whatsapp_id": "wamid.HBgMNTkzOTkxMjM0NTY3FQIAERgSMUQ3RjBBMkI2QjZBQTlGNjNBAA==",
"created_at": 1790546400,
"status_updated_at": 1790546412,
"expires_at": null,
"reply_to": null,
"interactive": null,
"location": null,
"reaction": null,
"referral": null
},
"pricing": {
"billable": true,
"category": "utility",
"type": "regular",
"model": "PMP"
}
}
}message.echo#
Alguien escribe desde la app WhatsApp Business del número.
{
"object": "event",
"id": "evt_02y9Hg6I37jaHgkutafuog",
"type": "message.echo",
"api_version": "v1",
"created_at": 1790547300,
"data": {
"message": {
"object": "message",
"id": "msg_02y9HflgNTRjaQMubfP6vm",
"number": {
"id": "num_02y8w48sgGf2ztA7qbjqso",
"phone": "+593969847312"
},
"contact": {
"phone": "+593991234567",
"user_id": null,
"name": null
},
"direction": "outbound",
"type": "text",
"text": "Le confirmo su cita del martes a las 10:00.",
"template": null,
"media": null,
"status": "sent",
"error": null,
"client_reference": null,
"sent_by": {
"type": "business_app"
},
"whatsapp_id": "wamid.HBgMNTkzOTkxMjM0NTY3FQIAERgSRUNITzEyMzQ1Njc4",
"created_at": 1790547299,
"status_updated_at": 1790547299,
"expires_at": null,
"reply_to": null,
"interactive": null,
"location": null,
"reaction": null,
"referral": null
}
}
}call.ended#
Termina una llamada saliente que el contacto contestó.
{
"object": "event",
"id": "evt_02y9Hg6I37jaHgkutafuog",
"type": "call.ended",
"api_version": "v1",
"created_at": 1790547400,
"data": {
"call": {
"object": "call",
"id": "call_02y8w6a0N4oqwFc47YdMac",
"number": {
"id": "num_02y8w48sgGf2ztA7qbjqso",
"phone": "+593969847312"
},
"contact": {
"phone": "+593991234567",
"user_id": null,
"name": "Ana Pérez"
},
"direction": "outbound",
"result": "completed",
"agent": {
"name": "Carlos Ruiz"
},
"created_at": 1790547190,
"started_at": 1790547200,
"ended_at": 1790547392,
"duration_sec": 192,
"billable_pulses": 32,
"error": null
}
}
}template.status#
Meta aprueba una plantilla.
{
"object": "event",
"id": "evt_02y9Hg6I37jaHgkutafuog",
"type": "template.status",
"api_version": "v1",
"created_at": 1790547600,
"data": {
"template": {
"object": "template",
"name": "recordatorio_cita",
"language": "es",
"status": "APPROVED",
"whatsapp_account": "wa_02y8w2MyKl4wS3UC9VNwwo"
},
"reason": null
}
}number.connected#
Se conecta un número.
{
"object": "event",
"id": "evt_02y9Hg6I37jaHgkutafuog",
"type": "number.connected",
"api_version": "v1",
"created_at": 1790200005,
"data": {
"number": {
"object": "number",
"id": "num_02y8w48sgGf2ztA7qbjqso",
"phone": "+593969847312",
"display_name": "Clínica Ejemplo",
"label": "Recepción",
"mode": "coexistence",
"status": "active",
"quality": "green",
"messaging_limit": "TIER_1K",
"can_send": "available",
"issues": [],
"whatsapp_account": {
"id": "wa_02y8w2MyKl4wS3UC9VNwwo",
"name": "Clínica Ejemplo",
"can_send": "available"
},
"connected_at": 1790200000
},
"reconnected": false
}
}number.disconnected#
El negocio desconecta el número desde su app.
{
"object": "event",
"id": "evt_02y9Hg6I37jaHgkutafuog",
"type": "number.disconnected",
"api_version": "v1",
"created_at": 1790548200,
"data": {
"number": {
"object": "number",
"id": "num_02y8w48sgGf2ztA7qbjqso",
"phone": "+593969847312",
"display_name": "Clínica Ejemplo",
"label": "Recepción",
"mode": "coexistence",
"status": "disconnected",
"quality": "green",
"messaging_limit": "TIER_1K",
"can_send": "available",
"issues": [],
"whatsapp_account": {
"id": "wa_02y8w2MyKl4wS3UC9VNwwo",
"name": "Clínica Ejemplo",
"can_send": "available"
},
"connected_at": 1790200000
},
"reason": "partner_removed",
"partner": {
"reason": "INACTIVITY",
"initiated_by": "BUSINESS"
}
}
}number.quality#
Baja la calidad de un número.
{
"object": "event",
"id": "evt_02y9Hg6I37jaHgkutafuog",
"type": "number.quality",
"api_version": "v1",
"created_at": 1790548800,
"data": {
"number": {
"object": "number",
"id": "num_02y8w48sgGf2ztA7qbjqso",
"phone": "+593969847312",
"display_name": "Clínica Ejemplo",
"label": "Recepción",
"mode": "coexistence",
"status": "active",
"quality": "yellow",
"messaging_limit": "TIER_1K",
"can_send": "available",
"issues": [],
"whatsapp_account": {
"id": "wa_02y8w2MyKl4wS3UC9VNwwo",
"name": "Clínica Ejemplo",
"can_send": "available"
},
"connected_at": 1790200000
},
"previous": {
"quality": "green",
"messaging_limit": "TIER_1K"
}
}
}number.status#
Un número deja de poder enviar.
{
"object": "event",
"id": "evt_02y9Hg6I37jaHgkutafuog",
"type": "number.status",
"api_version": "v1",
"created_at": 1790549400,
"data": {
"number": {
"object": "number",
"id": "num_02y8w48sgGf2ztA7qbjqso",
"phone": "+593969847312",
"display_name": "Clínica Ejemplo",
"label": "Recepción",
"mode": "coexistence",
"status": "active",
"quality": "green",
"messaging_limit": "TIER_1K",
"can_send": "blocked",
"issues": [
{
"code": 141006,
"title": "Falta un método de pago en la cuenta de WhatsApp Business",
"solution": "Meta no deja iniciar conversaciones hasta que se añada un método de pago válido en WhatsApp Manager → Configuración de pagos."
}
],
"whatsapp_account": {
"id": "wa_02y8w2MyKl4wS3UC9VNwwo",
"name": "Clínica Ejemplo",
"can_send": "blocked"
},
"connected_at": 1790200000
},
"previous": {
"can_send": "available"
}
}
}webhook.test#
«Enviar prueba», desde la consola o por la API.
{
"object": "event",
"id": "evt_02y9Hg6I37jaHgkutafuog",
"type": "webhook.test",
"api_version": "v1",
"created_at": 1790550000,
"data": {
"endpoint": "we_02y8w4hE8Lo89zo8KTrC1e",
"requested_at": 1790550000
}
}Rota el secreto sin cortes#
«Rotar el secreto» crea uno nuevo y mantiene el anterior el tiempo que elijas (24 horas recomendado). Durante ese tiempo cada aviso lleva dos firmas: pon el secreto nuevo en tu servidor cuando quieras y, pasado el plazo, el anterior deja de servir.
Tu URL y tu red#
- Solo
https://con un certificado válido para el dominio, en el puerto 443 u 8443. Sin IPs y sin direcciones internas. - No seguimos redirecciones: pon la URL final.
- Si tu servidor filtra por IP, los avisos salen de
187.6.167.5; te avisaremos antes de cambiarlas.
Prueba#
«Enviar prueba», en la página del endpoint, manda un aviso webhook.test firmado igual que los demás y te muestra qué respondió tu servidor: el código, cuánto tardó y el principio de la respuesta. Úsalo después de cada cambio en tu receptor. Desde tu sistema, lo mismo es POST /v1/webhook-endpoints/{id}/test.
Lo que puede cambiar#
Dentro de v1 solo añadimos: campos nuevos en los objetos, valores nuevos en los que vienen de Meta (estados de plantillas, calidad, precios) y tipos de evento nuevos (que solo recibes si los eliges). Ignora lo que no conozcas. Un cambio que rompa algo será v2, y tú eliges cuándo pasar.
- 9 de octubre de 2026 · v1. El evento
call.ended, al terminar cada llamada de WhatsApp (entrante o saliente, contestada o no), con su resultado, quién la atendió, la duración y los pulsos que cobra WhatsApp. Lleva datos de tus contactos, como los de mensajes. - 7 de octubre de 2026 · v1. Los endpoints también se gestionan por la API, y el OpenAPI publica el cuerpo de cada aviso en su sección
webhooks.number.disconnecteddeja de anunciar el motivoworkspace_closed, que nunca se enviaba: al cerrar un espacio, sus endpoints se eliminan antes. - 28 de septiembre de 2026 · v1. Primera versión: mensajes (recibidos, estados y ecos de la app), plantillas y números.