Buenas prácticas

Una integración robusta responde rápido, verifica cada envío, descarta duplicados y tolera cambios en el formato. Esta página resume qué hacer y dónde se explica cada práctica.

Resumen

Práctica	Qué hacer	Detalle
Responder rápido	Responda 2xx de inmediato y procese en segundo plano.	Entrega y reintentos
Verificar la firma	Verifique sobre el cuerpo crudo, con comparación en tiempo constante.	Autenticación y firma
Validar la marca de tiempo	Compare X-Webhook-Timestamp con la hora de su servidor y rechace diferencias de más de 300 segundos.	Autenticación y firma
Deduplicar	Guarde el event_id del cuerpo, ya verificado, y descarte los eventos ya procesados.	Entrega y reintentos
No depender del orden	Use las fechas y el estado del evento para decidir qué dato es más reciente.	Entrega y reintentos
Ignorar campos desconocidos	No falle ante campos nuevos.	Compatibilidad y versionado
Proteger el secreto	Guárdelo fuera del código fuente y de los registros.	Primeros pasos

Recepción

• Registre una URL final con HTTPS, sin redirecciones.
• Use el cuerpo crudo de la petición para verificar la firma. Analice el JSON solo después de verificarla.
• Responda 2xx también ante los tipos de evento (event_type) que no procesa. Una respuesta distinta de 2xx genera reintentos innecesarios.
• Ante una firma o una marca de tiempo inválidas, responda con un código distinto de 2xx (por ejemplo, 401) y no procese el evento.
• Encole el evento y procéselo de forma asíncrona. No haga llamadas a otros sistemas antes de responder.

Idempotencia

• Guarde el event_id del cuerpo de cada evento procesado, después de verificar la firma. Descarte los eventos con un identificador que ya vio. No use solo la cabecera X-Webhook-Id: no forma parte del mensaje firmado.
• Use también el par event_type y data.id como clave de negocio. El data.id se repite entre eventos distintos de la misma entidad.
• Diseñe el procesamiento para que ejecutarlo dos veces produzca el mismo resultado.

Datos

• Convierta los importes, que se envían como texto, con una librería decimal. No use números de coma flotante.
• Respete las columnas «Nulo» de cada evento: un campo que admite null puede llegar sin valor.
• No asuma un formato para event_id ni para los identificadores. Trátelos como texto opaco.
• Los eventos de órdenes y comprobantes incluyen datos personales completos del cliente final, como documento de identidad, correo, teléfono y dirección. Guárdelos solo si los necesita y protéjalos según la normativa de protección de datos personales aplicable a su organización.

Operación

• Mantenga el reloj de su servidor sincronizado: la validación de 300 segundos depende de él.
• Registre el event_id y el resultado del procesamiento de cada evento. No registre el secreto.
• Monitoree las respuestas que no son 2xx de su endpoint. Cinco intentos fallidos dejan el evento sin envío automático.
• Cuando reciba un evento con una api_version desconocida, regístrelo y avise a su equipo.

Checklist

• Verifico la firma sobre el cuerpo crudo con comparación en tiempo constante.
• Rechazo las marcas de tiempo con más de 300 segundos de diferencia.
• Respondo 2xx antes de procesar.
• Descarto duplicados por el event_id del cuerpo, después de verificar la firma.
• No dependo del orden de llegada.
• Ignoro los campos que no reconozco.
• Mantengo el secreto fuera del código fuente y de los registros.