Tiempo de lectura estimado : 6 min · Publicado
Escribir el contrato del evento
Documente el productor, los tipos de eventos esperados, los campos obligatorios y la operación activada. Describa los resultados para la creación, el cambio y la eliminación cuando corresponda. Una notificación no debe autorizar implícitamente todas las acciones posibles.
Elija un identificador de seguimiento y una fuente autorizada para consultar cuando esté incierto. Describa cómo se detectan las fallas en el productor o receptor. La documentación de integración contiene reglas y propietarios; Los secretos pertenecen al mecanismo seguro del proyecto.
En n8n, las URL de webhook de prueba y producción tienen usos distintos. Escuchar un evento de prueba no prepara la recepción habitual: la URL de producción se registra al publicar el workflow. Compruebe la URL configurada en el emisor y consulte las ejecuciones de producción en Executions.
El modo de respuesta cambia el significado del acuse. Con Immediately, la respuesta indica el inicio del workflow, no la actualización del pedido o de la ficha cliente. Relacione identificador de evento, ejecución y estado final del destino antes de anunciar el éxito de la operación.
Desplace la tabla horizontalmente para leer todas las columnas. Con el teclado, sitúe el foco en la tabla y use las flechas.
| Punto de control | Observación posible | Evidencia esperada |
|---|---|---|
| URL de prueba | Evento visible durante la escucha de prueba | URL y entorno utilizados |
| URL de producción | Workflow publicado y ejecución registrada | Identificador de ejecución vinculado al evento |
| Respuesta Immediately | El workflow ha comenzado | Estado final y operación prevista en el servicio destino |
Verificar antes de activar una operación
Validación de firma de entrega de documentos de GitHub utilizando la carga útil Secreto y recibido. seguir el mecanismo documentado del proveedor real; Los encabezados, algoritmos y formatos no deben copiarse de otro servicio por analogía.
Verificación de origen separada, validación de esquema y autorización de operación. Pruebe el contenido alterado, un tipo de evento inesperado y un campo faltante. El procesamiento comercial debe comenzar solo después de los controles requeridos para el caso de uso.
Planificar repeticiones e interrupciones
Definir manejo idempotente: una entrega repetida reconocida no debe crear dos pedidos o dos notificaciones finales. Prueba de repetición antes, durante y después del procesamiento y una interrupción entre pasos. El mecanismo depende de la operación y el almacenamiento involucrado.
Compruebe las garantías de pedido y reenvío del proveedor en lugar de asumir una llegada inmediata y única. Mantenga una cola de trabajo que requiere revisión y una forma de reconciliarla con la fuente. Una respuesta técnica positiva debe corresponder a un estado de procesamiento definido.
Organizar el monitoreo y la recuperación
Registre un identificador de evento, un estado y un error útil al minimizar los datos. Defina quién monitorea los fallos, cómo se vuelven a intentar los eventos autorizados y cómo los reintentos evitan duplicar el trabajo terminado.
Interrumpir al receptor en un entorno de prueba y restaurarlo. Comprobar la recuperación y conciliar los resultados de negocio esperados. Entregue un contrato de evento, lote de prueba, historial de procesamiento y procedimiento de recuperación que el equipo pueda utilizar.
Documentación principal: GitHub : Validación de entregas de webhooks.
Ejemplo ficticio: DEMO-E41 provoca una sola escritura de negocio en una base de datos. El contrato agrupa esa escritura y la marca de evento procesado en la misma transacción; una clave única que combina productor e identificador controla el procesamiento concurrente. Pruebe una interrupción antes y después de COMMIT. La recuperación posterior encuentra el trabajo completado en lugar de añadir otro efecto. Anotar «recibido» en un registro separado no ofrece esa garantía.
En GitHub, una reentrega mantiene el valor de X-GitHub-Delivery; un nuevo intento no es por ese solo motivo un evento nuevo. Verifique por separado a cada productor. DEMO-E42 muestra otro límite: una llamada a un servicio externo agota el tiempo sin respuesta. Una transacción local no permite saber si ese servicio actuó; contraste su referencia y las garantías de reintento documentadas antes de repetir la acción.
Desplace la tabla horizontalmente para leer todas las columnas. Con el teclado, sitúe el foco en la tabla y use las flechas.
| Caso de prueba | Efecto de negocio establecido | Recuperación esperada |
|---|---|---|
| DEMO-E41 antes de COMMIT, transacción revertida | 0 efectos confirmados | Recuperar según el registro transaccional |
| DEMO-E41 después de COMMIT | 1 efecto y evento marcado como procesado | Recuperar el resultado ya confirmado |
| DEMO-E41 entregado otra vez | Sigue habiendo 1 efecto en total | Reconocer la clave; no repetir la escritura |
| DEMO-E42: llamada externa sin respuesta | Resultado desconocido: puede haber 0 o 1 efecto | Contrastar con el servicio; evitar repetir a ciegas |
- GitHub : Webhook Best Practices
GitHub, consultado el 22 de octubre de 2026: identificador conservado en la reentrega. DEMO-E41 y DEMO-E42 son eventos abreviados ficticios.
- PostgreSQL : Transactions
PostgreSQL, consultado el 22 de octubre de 2026: transacciones de base de datos, sin garantía global para llamadas externas.
Documentos de referencia
- Stripe : Webhooks · Fuente consultada
- n8n : Webhook node · Fuente consultada
- GitHub : Validación de entregas de webhooks
Contenido actualizado
Referencias documentadas para este tema
| Referencia | Valor o sintaxis | Alcance |
|---|---|---|
| RFC 8259 · JSON | application/json · UTF-8 | JSON estándar no admite comentarios ni comas finales; las cadenas usan comillas dobles. |
| RFC 3339 · Date-time | 2026-10-22T09:00:00+02:00 | El desfase explícito relaciona la hora local con UTC; este ejemplo no es una cita. |
Las fechas indican la consulta de las referencias. Estos datos no constituyen una auditoría ni una declaración global de conformidad.
