Desarrolladores

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.

CabeceraQué es
webhook-idEl 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-timestampCuándo salió este intento, en segundos desde 1970 (UTC).
webhook-signatureUna o dos firmas v1,… separadas por espacios (dos mientras rotas el secreto).
stacknetic-event-typeEl 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#

  1. Lee el cuerpo crudo, sin volver a serializarlo.
  2. Rechaza si webhook-timestamp se aleja más de 5 minutos de tu hora.
  3. Calcula HMAC-SHA256 con la clave (la parte en base64 que sigue a whsec_, decodificada) sobre {webhook-id}.{webhook-timestamp}.{cuerpo}, en base64.
  4. Acepta si coincide, en tiempo constante, con alguna de las firmas v1,… de webhook-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);
}

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-id para 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. failed es final, salvo que su error.code sea uno de los que Meta puede desmentir (expired, unknown_outcome, workspace_inactive, channel_unavailable, channel_blocked, internal): entonces un sent posterior manda.
  • Usa status_updated_at del 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.

TipoMensajesCuándo
message.receivedMensaje recibidoUn contacto escribe a uno de tus números.
message.statusEstado de un mensajeUn mensaje que enviaste se envió, se entregó, se leyó o falló.
message.echoMensaje desde el teléfonoAlguien escribió desde la app WhatsApp Business del número.
TipoLlamadasCuándo
call.endedLlamada terminadaTerminó una llamada de WhatsApp, entrante o saliente, contestada o no: con su resultado, quién la atendió y cuánto duró.
TipoPlantillasCuándo
template.statusEstado de una plantillaMeta aprobó, rechazó, pausó o desactivó una plantilla.
TipoNúmerosCuándo
number.connectedNúmero conectadoSe conectó o se reconectó un número.
number.disconnectedNúmero desconectadoUn número dejó de estar conectado.
number.qualityCalidad del númeroCambió la calidad o el límite de mensajes de un número.
number.statusEstado del númeroUn 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.

resultQué pasó
completedHubo conversación: trae started_at, duration_sec y, si fue saliente, billable_pulses.
missedUna entrante que nadie contestó. Desde la consola se puede devolver.
no_answerUna saliente que el contacto no contestó.
declinedEl contacto rechazó la saliente.
canceledQuien llamaba colgó antes de que contestaran.
failedUn error de WhatsApp o de conexión: su código y su título, en error.
expiredNo 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.disconnected deja de anunciar el motivo workspace_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.