Campos de registro de entrega de webhook para una depuración de respuestas segura
Un esquema de entrega útil normaliza los campos de intento, mantiene el código de estado final y los metadatos de respuesta limitados, y excluye URL, encabezados de solicitud, autorización, cargas útiles y contenido de respuesta sin procesar.
- 1
Finaliza la entrega
Emitir una vez después del éxito o del agotamiento permanente del reintento, no una vez por línea de registro.
- 2
Los campos están normalizados.
Asigne campos de origen como attempt_number a attempt_count y luego mantenga status_code, response_body_bytes y un tipo de contenido incluido en la lista de permitidos en lugar de response_body sin formato.
- 3
Los secretos permanecen fuera
Nunca almacene request_headers, valores de autorización, URL de clientes ni cargas útiles de webhooks.
- 4
La recuperación se mide
Compare fallas permanentes, códigos de estado recurrentes y recuperación después de reintentos por tipo de destino.
grano
Un resultado de terminal por entrega de webhook lógico.
propietario
Trabajador de entrega de webhook
Emitir cuando
Después del éxito o del agotamiento permanente del reintento.
Contrato de campo
Tipos de campos y datos que debes excluir
Mantenga estables los nombres y tipos de campos existentes después de que las consultas de producción dependan de ellos. El contexto opcional debe permanecer limitado, documentado y justificado por una decisión específica.
| Campo | Tipo | Requerido | Privacidad | Significado |
|---|---|---|---|---|
| timestamp_utc | timestamp | yes | non-sensitive | Hora UTC en el límite del resultado. |
| event_id | string | yes | non-sensitive | Identificador único estable utilizado para la deduplicación. |
| release | string | yes | non-sensitive | Versión de la aplicación o servicio que emitió el evento. |
| account_id | string | yes | pseudonymous | Identificador de cuenta interno estable, nunca un correo electrónico o nombre. |
| delivery_id | string | yes | pseudonymous | Identificador de entrega lógica estable. |
| destination_type | string | yes | non-sensitive | Categoría de integración limitada, no una URL de destino. |
| attempt_count | number | yes | non-sensitive | Intentos a través del resultado terminal. |
| status_code | number | no | non-sensitive | Estado HTTP final cuando existe una respuesta. |
| response_body_bytes | number | no | non-sensitive | Tamaño del cuerpo de respuesta final en bytes. Almacene el tamaño en lugar del cuerpo de la respuesta. |
| response_content_type | string | no | review | Tipo de medio de respuesta permitido, como aplicación/json; nunca copie encabezados de respuesta sin restricciones. |
| status | string | yes | non-sensitive | Entregado o fallado permanentemente. |
Evento JSON sintético
{
"timestamp_utc": "2026-07-28T14:29:08Z",
"event_id": "evt_webhook_01",
"account_id": "acct_8f31",
"release": "2026.07.2",
"delivery_id": "delivery_09cc",
"destination_type": "slack",
"attempt_count": 1,
"status_code": 200,
"response_body_bytes": 27,
"response_content_type": "application/json",
"status": "delivered"
}Revisión de privacidad
Revisar los identificadores antes de la ingestión
Este ejemplo utiliza identificadores sintéticos. Los valores seudónimos aún pueden ser datos personales y los campos de revisión pueden exponer el contexto empresarial o del proveedor. Aplique sus propios requisitos de consentimiento, retención, acceso, residencia y eliminación.
account_id: pseudonymousdelivery_id: pseudonymousresponse_content_type: review
Lista de verificación de validación
Pruebe el contrato antes de crear un panel
- Send one known webhook_delivery_completed fixture after the documented outcome boundary.
- Verify all 8 required fields arrive with the documented types.
- Vuelva a intentar el mismo identificador de evento y confirme el comportamiento de deduplicación elegido.
- Envíe un error controlado o un resultado alternativo cuando el flujo de trabajo lo admita.
- Ejecute el SQL relacionado en una ventana fija y concilie el resultado con el dispositivo.
Errores comunes
Mantenga una fila igual a un resultado duradero
- Emitting webhook_delivery_completed before webhook delivery worker knows the final outcome.
- Mezclar varios granos en una tabla, lo que hace que los recuentos y tasas sean ambiguos.
- Reemplazar categorías controladas con URL sin formato, cargas útiles, mensajes o texto de error.
- De ello depende el cambio de un tipo de campo después de las consultas y los paneles guardados.
- Agregar identificadores sin una necesidad documentada de investigación, acceso y retención.
Usa el contrato
Consultar y operacionalizar el evento.
Contratos relacionados
Envía un evento de prueba antes del tráfico de producción
Cree una clave API gratuita, envíe el evento sintético e inspeccione la tabla inferida antes de conectar un flujo de trabajo en vivo.