Recepción de webhooks entrantes: bytes originales, HMAC y deduplicación
Los endpoints de recepción de Meta (WhatsApp, Instagram y Messenger) validan la firma criptográfica X-Hub-Signature-256 directamente sobre el buffer crudo de bytes originales (rawBody) antes de interpretar el JSON. Cada mensaje entrante de WhatsApp se deduplica por su identificador wamid y, cuando varios mensajes comparten el mismo segundo del proveedor, se ordenan de forma determinista mediante received_at.
En los cobros de Yappy Comercial V2 —tanto para ventas del negocio como para la suscripción SaaS de plataforma— el servidor verifica la firma HMAC-SHA256 sobre los parámetros de la orden, comprueba el comercio y el ambiente, y aplica la transición monotónica a paid únicamente ante un IPN válido de producción.
Contrato de los webhooks salientes de EMP
Cuando habilitas los avisos salientes hacia un sistema propio del negocio, el worker realiza primero una comprobación del receptor y firma cada evento con HMAC-SHA256.
| Aspecto | Contrato técnico | Comportamiento ante errores o cortes de red |
|---|---|---|
| Verificación del receptor | Exige HTTPS hacia orígenes públicos autorizados y respuesta GET con mrCalendarProtocol: "1" y supportsDeduplication: true. | Bloquea direcciones IP privadas/locales y rechaza configurar destinos que no declaren soporte de deduplicación. |
| Firma y privacidad del payload | Envía cabeceras X-MR-Calendar-Event, X-MR-Calendar-Timestamp y X-MR-Calendar-Signature (v1=HMAC-SHA256). | Publica únicamente metadatos del evento (por ejemplo, order.confirmed o booking.confirmed) sin filtrar notas privadas ni texto de clientes. |
| Reintentos y estado incierto | Reintenta hasta un máximo de 3 veces solo cuando el receptor responde con rechazo explícito retryable: true. | Si la conexión se corta sin respuesta tras enviar el POST, marca la entrega como uncertain y no la repite automáticamente. |
Revocación de permisos antes del despacho
Si el miembro que configuró el webhook saliente pierde su rol de propietario o administrador antes de que el worker procese un aviso en cola, la entrega pendiente se cancela automáticamente sin realizar la llamada HTTP externa.
Antes de continuar
- Valida siempre la firma HMAC sobre el cuerpo original y utiliza el ID del evento para deduplicar en tu receptor.
- Configura tus receptores HTTPS para responder de forma idempotente y declarar explícitamente si un rechazo es reintentable.
- Revisa manualmente cualquier entrega marcada como uncertain antes de forzar un reenvío.
La demo conserva datos en memoria. Las conexiones de proveedores requieren configuración, autorización y verificación en tu entorno persistente.