Webhooks firmados con HMAC para el ciclo de vida del off-ramp.
Cuando tu producto necesita estado asíncrono del ciclo de vida, registra endpoints de webhook y verifica cada entrega. La firma vincula el timestamp al cuerpo crudo exacto para que puedas rechazar payloads manipulados o reenviados.
Eventos del ciclo de vida
| Evento | Significado |
|---|---|
| deposit.created | Se creó un depósito de vendedor en Base |
| deposit.partially_filled | Un depósito se rellenó en parte |
| deposit.filled | Un depósito se rellenó por completo |
| deposit.closed | Un vendedor cerró o retiró el saldo restante |
| otc.taken | Un depósito OTC privado fue tomado por el comprador aprobado |
Verifica cada entrega
- 1Lee la cabecera X-Usdctofiat-Signature con el formato t=<unix>,v1=<hex>.
- 2Construye el payload firmado como la cadena timestamp.rawBody usando el cuerpo crudo sin parsear.
- 3Calcula HMAC-SHA256 sobre ese payload con el secreto de tu endpoint.
- 4Compara en tiempo constante contra el valor hex v1 antes de confiar en el evento.
- 5Opcionalmente, rechaza las entregas cuyo timestamp sea más antiguo que la ventana que elijas.
La protección contra reenvíos es decisión tuya
El receptor de referencia del repo de starters trata los timestamps de más de 5 minutos como obsoletos para protegerse de reenvíos. Esa ventana la impone tu verificador, no el emisor, así que puedes ajustarla o ampliarla según tu latencia y tu tolerancia a reintentos.
Como la firma cubre timestamp.rawBody, parsea el JSON solo después de que pase la comprobación HMAC. Verificar el objeto parseado en lugar de los bytes crudos es la forma más común de equivocarse de manera sutil en la verificación de firma.
Registra y opera
- Registra endpoints con tu API key de Peerlytics; una sola key autentica las superficies de offramp y de Peerlytics.
- Los endpoints que acumulan fallos de entrega consecutivos repetidos pueden deshabilitarse hasta que los arregles.
- Usa el receptor del repo de starters como referencia conocida y correcta de verificación HMAC.
- Trata los webhooks como pistas de estado; reconcilia contra la verdad onchain con deposits() cuando importe.
Keep exploring
Common questions
¿Cómo se firman los webhooks de USDCtoFiat?
Cada entrega lleva X-Usdctofiat-Signature: t=<unix>,v1=<hex>, un HMAC-SHA256 sobre la cadena timestamp.rawBody. Vuelve a calcular el HMAC con el secreto de tu endpoint sobre el cuerpo crudo y compara en tiempo constante antes de confiar en el evento.
¿Cómo evito webhooks reenviados?
Rechaza las entregas cuyo timestamp firmado sea más antiguo que una ventana que tú elijas. El receptor de referencia usa 5 minutos. El emisor no impone ninguna ventana, así que es responsabilidad de tu verificador.
¿Necesito una API key para los webhooks?
Sí. Crear depósitos es permissionless, pero registrar endpoints de webhook usa una API key de Peerlytics. La misma key también autentica la API de Peerlytics.