Una URL pública de recepción puede recibir solicitudes de cualquiera. Un atacante puede enviar un evento fabricado a esa URL, así que la solicitud necesita autenticación antes de activar cualquier trabajo.
Bird usa el esquema de firma de Standard Webhooks. Autentica el identificador del evento y la hora del intento junto con el cuerpo, de modo que cambiar cualquiera de ellos invalida la firma.
¿Qué firma Bird?
Bird firma el identificador del evento, la marca de tiempo del intento de entrega y el cuerpo crudo de la solicitud, unidos con puntos.
Mantén el cuerpo de la solicitud sin cambios hasta que verifiques la firma. Parsear y serializar JSON puede cambiar los bytes que Bird firmó.
| Encabezado | Qué contiene |
|---|---|
webhook-id | El identificador del evento, reutilizado en reintentos y repeticiones. |
webhook-timestamp | La hora del intento como marca de tiempo Unix en segundos. |
webhook-signature | Una o más firmas, separadas por espacios. Cada una comienza con v1,. |
Convierte la marca de tiempo de segundos antes de compararla con un reloj que informa en milisegundos.
Elimina el prefijo whsec_ del secreto de tu endpoint y decodifica en base64 el resto para recuperar los bytes de la clave.
Une el identificador, la marca de tiempo y el cuerpo intacto con puntos. Calcula HMAC-SHA256 sobre esa cadena usando la clave decodificada. Compara el resultado con cada firma proporcionada usando una comparación en tiempo constante, cuyo tiempo de ejecución no revela qué bytes coinciden.
¿Por qué mi firma nunca coincide?
Un secreto incorrecto o un cuerpo de solicitud modificado pueden hacer que toda verificación de firma falle.
Los frameworks web suelen parsear JSON antes de que tu handler se ejecute. Serializar ese objeto de nuevo puede cambiar espacios, orden de claves o formato numérico. El JSON resultante puede significar lo mismo pero producir una firma diferente.
Configura esta ruta para conservar su cuerpo crudo. Comprueba que el secreto pertenece a este endpoint, especialmente después de un despliegue o una rotación.
¿Qué debe rechazar mi handler?
Rechaza una solicitud cuando ninguna firma coincide o su marca de tiempo firmada queda fuera de la ventana de tiempo permitida.
Prueba cada firma en webhook-signature. Durante la rotación de secretos, una entrega lleva firmas de múltiples secretos válidos. Aceptar cualquier firma que coincida permite que los receptores que usan cualquiera de los secretos sigan funcionando.
Usa una tolerancia de cinco minutos en la marca de tiempo a cada lado de tu reloj. Una solicitud capturada de diez minutos antes entonces falla aunque su firma no haya cambiado. Mantén el reloj de tu servidor preciso para no rechazar entregas legítimas.
Comprueba webhook-id contra los eventos que ya almacenaste. Un duplicado reconocido debe recibir éxito sin repetir su trabajo, ya que reintentar la misma entrega no añade un evento nuevo.
¿Qué sucede si rechazo una entrega?
Bird reintenta una entrega que recibe una respuesta de error o ninguna respuesta antes de su tiempo límite.
Una respuesta 400, por ejemplo, registra el rechazo y deja la entrega elegible para reintento. Todas las respuestas que no son 2xx siguen la política de reintentos. El código te ayuda a diagnosticar el fallo en tus registros.
El calendario abarca aproximadamente 27,5 horas antes de ajustes, lo que te da tiempo para corregir un secreto incorrecto. Reintentos de webhooks fallidos describe el calendario y cómo repetir eventos perdidos después.
Devuelve 2xx solo después de haber verificado y almacenado el evento de forma segura, o de haber reconocido un duplicado ya almacenado. Bird omite las entregas exitosas durante la repetición, así que confirmar una solicitud no verificada impide la recuperación mediante ese mecanismo.
¿Tengo que implementar la verificación yo mismo?
No necesitas implementar la verificación tú mismo cuando usas webhooks.unwrap en un Bird SDK. Pásale el cuerpo crudo y los encabezados de la solicitud.
El helper comprueba la firma y la marca de tiempo antes de devolver el evento decodificado. Tu aplicación aún deduplica por webhook-id, porque ella es la dueña del registro de trabajo completado.
Una biblioteca de verificación compatible con Standard Webhooks puede realizar las mismas comprobaciones. La guía de webhooks incluye ejemplos y una implementación manual.
En resumen
Verifica los bytes originales.
Parsear y serializar JSON puede cambiar los bytes que Bird firmó. Conserva el cuerpo crudo para la verificación.
Comprueba el tiempo además de la firma.
Una tolerancia de cinco minutos en la marca de tiempo limita la reutilización de solicitudes capturadas. Deduplica los eventos almacenados por webhook-id de forma independiente.
Prueba cada firma proporcionada.
La rotación crea firmas superpuestas. Una coincidencia con cualquier firma válida permite que el despliegue continúe.
Confirma solo eventos verificados y almacenados.
Bird reintenta las respuestas que no son 2xx y omite las entregas exitosas durante la repetición. Devuelve éxito para duplicados ya almacenados sin repetir su trabajo.