What are webhooks?
Webhooks are HTTP notifications that Taxo sends to your application when important events occur, such as the completion of an extraction. Instead of constant polling, your application receives updates automatically.Real-time
Receive instant notifications when documents are ready
Efficiency
Eliminates the need for constant API polling
Reliability
Automatic retry system with exponential backoff
Security
HMAC-SHA256 signature verification to authenticate events
Webhook configuration
1
Access dashboard
Go to Taxo Dashboard → Settings → Webhooks
2
Create endpoint
Click “Add Webhook” and enter your endpoint URL
3
Select events
Choose the types of events you want to receive:
extraction.completed- Extraction completed successfullyextraction.failed- Extraction faileddocument.ready- Individual document ready for download
4
Configure security
Optionally, configure a secret to verify HMAC signatures
5
Test connection
Use the “Test Webhook” button to verify that your endpoint responds correctly
Event types
extraction.completed
Sent when an extraction completes successfully.extraction.failed
Sent when an extraction fails due to an unrecoverable error.document.ready
Sent for each document that is processed successfully (optional, may generate many notifications).Webhook endpoint implementation
Signature verification
Webhooks include an HMAC-SHA256 signature to verify their authenticity:1
Get data
timestamp: HeaderX-Taxo-Timestampsignature: HeaderX-Taxo-Signaturepayload: Body raw del webhook
2
Build string to sign
Concatenate:
timestamp + "." + payload3
Calculate HMAC
Use your webhook secret to calculate HMAC-SHA256 of the previous string
4
Compare signatures
The received signature should equal
sha256={your_calculated_hmac}Best practices
Idempotencia
Idempotencia
Los webhooks pueden enviarse múltiples veces. Usa el campo
event.timestamp como clave de idempotencia para evitar procesamiento duplicado.Timeouts y reintentos
Timeouts y reintentos
Configura timeouts apropiados en tu endpoint:
- Timeout de respuesta: 10 segundos máximo
- Procesamiento asíncrono: Para tareas largas, responde 200 inmediatamente y procesa en background
- Reintentos automáticos: Taxo reintentará hasta 5 veces con backoff exponencial
Logging y monitoreo
Logging y monitoreo
Implementa logging detallado para debugging:
Seguridad
Seguridad
- HTTPS obligatorio: Los webhooks solo se envían a URLs HTTPS
- Verificar firma: Siempre valida la firma HMAC en producción
- Validar timestamp: Rechaza webhooks muy antiguos (más de 5 minutos)
- Rate limiting: Implementa protección contra ataques de denegación de servicio
Testing and debugging
Test webhooks locally
To test webhooks in local development, use tools like ngrok:Test webhook
You can test your endpoint with this example payload:Troubleshooting
Webhook no se recibe
Webhook no se recibe
- Verifica que la URL esté configurada correctamente
- Asegúrate de que tu endpoint responda con status 2xx
- Revisa que no haya firewalls bloqueando las IPs de Taxo
- Confirma que el certificado SSL sea válido
Error de firma inválida
Error de firma inválida
- Verifica que el secreto webhook esté configurado correctamente
- Asegúrate de usar el body raw (no parseado) para calcular la firma
- Confirma que estás concatenando timestamp + ”.” + payload
- Verifica que el algoritmo sea HMAC-SHA256
Webhooks duplicados
Webhooks duplicados
- Implementa idempotencia usando el timestamp del evento
- Almacena IDs de eventos procesados en cache/base de datos
- Responde siempre con 200 even si el evento ya fue procesado