Algebraix notifica a tu sistema con un POST cada vez que ocurre un cambio en los datos que
hayas suscrito. Esta sección describe el contrato de entrega: qué esperamos de tu endpoint,
cuántas veces reintentamos y cómo debes tratar los eventos duplicados.
| Respuesta | Interpretación | ¿Reintentamos? |
|---|---|---|
2xx |
Entregado | No |
500, 502, 503, 504, 524 |
Error temporal de tu servidor | Sí |
408, 429 |
Timeout o límite de tasa alcanzado | Sí |
409 |
El evento requiere que otro se procese primero | Sí |
401, 403, 404 y demás 4xx |
Error permanente | No |
Responde 2xx en cuanto recibas el evento, sin esperar a procesarlo. Si tu procesamiento es
lento, encólalo de tu lado: un timeout de nuestra parte cuenta como fallo y provoca un
reintento innecesario.
Cualquier 4xx distinto de 408, 409 y 429 lo interpretamos como un error que no se va a
resolver por sí solo —credenciales inválidas, endpoint inexistente— y el evento se descarta
sin reintentos. Si tu endpoint necesita rechazar un evento de forma temporal, responde 503.
Un evento que no se entregue se reintenta hasta 6 veces, con esperas crecientes:
| Intento | Espera desde el anterior | Tiempo acumulado |
|---|---|---|
| 1 – 2 | inmediato | 0 |
| 3 | 1 minuto | 1 min |
| 4 | 15 minutos | 16 min |
| 5 | 1 hora | 1 h 16 min |
| 6 | 2 horas | 3 h 16 min |
Tras el sexto intento el evento se abandona. La ventana total es de aproximadamente 3 horas y 16 minutos: una interrupción de tu servicio más corta que eso no pierde eventos, se entregan cuando vuelva a responder.
La entrega es at-least-once, así que un evento puede llegarte más de una vez. El caso más
común es que tu servidor reciba el POST y procese el evento, pero su respuesta no alcance a
llegarnos: para nosotros es un fallo y lo reintentamos.
Cada request incluye dos headers para que puedas detectarlo:
| Header | Contenido |
|---|---|
x-webhook-id |
Identificador único del evento. Es el mismo en todos sus reintentos. |
x-webhook-attempt |
Número de intento, empezando en 1 |
Registra los x-webhook-id que ya procesaste y descarta las repeticiones. No uses el contenido
del payload para deduplicar: dos eventos distintos pueden tener cuerpos idénticos.
No garantizamos el orden. Un evento puede llegarte antes que otro del que depende — por ejemplo, el pago de un cargo antes que el cargo mismo.
Si detectas esa situación, responde 409 Conflict. Reintentaremos ese evento más tarde según
la tabla de arriba, sin reducir el ritmo de envío del resto de tus eventos.
Si tu endpoint es https, debe servir la cadena de certificados completa, incluidos los
intermedios. Los navegadores completan por su cuenta las cadenas incompletas; nuestro cliente
HTTP no lo hace. Una cadena incompleta es la causa más frecuente de fallos de entrega que no
dejan ningún rastro en tu servidor, porque la conexión nunca llega a establecerse.
Cada endpoint tiene una tasa configurable de requests por minuto, que puedes acordar con tu contacto en Algebraix. Ante errores o timeouts reducimos el ritmo automáticamente y lo recuperamos de forma gradual cuando tu servidor vuelve a responder con normalidad.