Hacer que los webhooks y las integraciones de sitios web sean confiables

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.

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.