Delivery and retries
Alfe stores every authentic event before it replies to the sender, so a 200 means the
event is stored. Within the 24-hour retention period, delivery is at-least-once, so design
your agent’s handling to cope with an occasional repeat. An event that isn’t delivered in
that time expires, so keep your own copy if you can’t afford to lose one.
Response codes
Section titled “Response codes”Your sender gets one of these:
| Status | Meaning | What the sender should do |
|---|---|---|
200 OK |
Alfe accepted the event. The body includes a deliveryId, or duplicate: true for a repeat, which has no deliveryId. |
Nothing. |
401 Unauthorized |
The X-Alfe-Signature-256 header is missing or doesn’t match. |
Fix the signature. Don’t retry unchanged. |
404 Not Found |
No active webhook exists at that URL. | Stop sending. |
413 Payload Too Large |
The body is over 256 KiB. | Send a smaller body. |
500 Internal Server Error |
Alfe couldn’t look up or verify the webhook. | Retry later. |
502 Bad Gateway |
The event was authentic, but Alfe couldn’t store it. | Retry later. |
A successful response looks like this:
{ "received": true, "deliveryId": "wdl_01J9Z…" }The body can be JSON or any other text. Alfe parses JSON when it can and passes anything else along as a string.
When your agent is online or offline
Section titled “When your agent is online or offline”Alfe replies to the sender without waiting for your agent to finish. Then:
- If your agent is online, Alfe delivers the event right away. It stays
pendinguntil the agent’s runtime accepts it, then becomesdelivered. - If your agent is offline, the event waits. Alfe delivers it when the agent reconnects, so a restart or a network blip doesn’t lose events.
Waiting events expire after 24 hours, so a longer outage can lose them. If that matters, have your sender keep its own record so it can resend.
On terminal runtimes, events are recorded rather than pushed into a conversation. See What happens when an event arrives.
Duplicate deliveries
Section titled “Duplicate deliveries”The same event can arrive twice, for example when a sender retries because it didn’t see
your 200 in time. Alfe filters out a repeat when the request carries a stable ID.
It looks for these headers first:
X-GitHub-DeliverySvix-IdIdempotency-KeyX-Webhook-IdandX-Delivery-IdCe-Id(CloudEvents)X-Slack-Request-IdX-Amz-Sns-Message-Id(Amazon SNS)
If there’s no header, webhooks tagged stripe use the body’s id, and webhooks tagged
slack use the body’s event_id.
A repeat gets a 200 and isn’t delivered again:
{ "received": true, "duplicate": true }Set Idempotency-Key when you send your own events, so retries are safe.
Build for at-least-once delivery
Section titled “Build for at-least-once delivery”Even with duplicate filtering, an event can occasionally reach your agent twice, such as after a crash at the wrong moment. A request with no recognized ID also can’t be filtered. So a few habits help:
- Make handling idempotent. Key the work on a stable field, such as an event ID, so running it twice does no harm.
- Give your agent a clear instruction. Tell it how to recognize an event it has already handled.
- Have your sender retry on errors. Retry on
500and502, but not on401or404.
Next steps
Section titled “Next steps”- Agent webhooks overview: see how webhooks are addressed and secured.
- Create and manage webhooks: create, rotate, and delete webhooks.
- Webhook signatures: sign requests for Alfe.