Reintentos y entrega (borrador)

Borrador técnico en inglés · no operativo

Los webhooks salientes todavía no entregan eventos. El cuerpo en inglés que sigue conserva una propuesta técnica: no es un contrato publicado ni una guía para activar una función disponible. No implementes una integración de producción contra estos ejemplos. La API pública actual ofrece suscriptores; consulta la hoja de ruta.

Fluyio webhooks are designed for at-least-once delivery: if your endpoint does not acknowledge a delivery, it will be retried with exponential backoff before being marked as failed. This page describes that model so you can build your receiver against it now.

What will count as a successful delivery

Response	Outcome
`2xx` within 10 seconds	Success. The delivery is closed.
`3xx`	Failure. Redirects are not followed.
`4xx`	Failure. Retried.
`5xx`	Failure. Retried.
No response within 10 seconds	Timeout. Treated as a failure.
Connection refused, DNS or TLS error	Failure. Retried.

Retry schedule

Failed deliveries will be retried with exponential backoff — minutes between the first attempts, hours between the last ones — for roughly a day and a half before the delivery is marked failed. The exact schedule will be published here when delivery ships.

Retries are per delivery, not per event. If your endpoint is down for ten minutes while 1,000 events are emitted, each event gets its own retry schedule and they all arrive when you come back.

Endpoint states

These are the states the dashboard already uses for an endpoint:

State	Meaning
`enabled`	Default. Deliveries will be attempted.
`failing`	Repeated failures detected. Deliveries continue; check your receiver.
`disabled`	Turned off, by you or automatically after sustained failure. No deliveries. Re-enable from the dashboard.

Inspecting deliveries

The Webhooks screen in the dashboard has a deliveries log per endpoint: event type, status (pending, success, failed, retrying), the response code and body your server returned, and a Retry button for individual deliveries. There is no public API for deliveries yet.

Designing for retries

Make your handler idempotent. The same event can arrive more than once (a 200 you sent might never reach us). Dedupe on event.id. See best practices.
Respond fast. The 10-second budget includes the TLS handshake, the body upload and your processing. Acknowledge early; do the work in a queue.
Do not retry inside your handler. If your database is down, return 503 and let Fluyio retry. Holding the connection past 10 seconds only causes a timeout.
Expect bursts. When you come back online after downtime, every pending retry hits you at once. Provision your endpoint accordingly or put a queue in front of it.

Out-of-order deliveries

Retries can make events arrive in a different order from the one in which they were generated. Trust the created timestamp in the envelope, not the arrival order, when reconstructing state. See ordering.