Delivery & Retries

Delivery expectations

Your endpoint must:

• Be served over HTTPS from a public address. URLs that point at private, local or internal addresses, including hostnames that resolve to one, are rejected when you save them and are never sent to.
• Have a hostname that resolves when you save it. Plirin looks the name up on save and refuses an endpoint whose name does not resolve within a few seconds, so create the DNS record before adding the endpoint. Each delivery looks the name up again and connects only to an address that passed the check.
• Answer directly, without redirecting. A 3xx response is not followed and counts as a failed attempt.
• Accept POST requests
• Return a 2xx status code within 10 seconds
• Any non-2xx response (or timeout) is treated as a failure

Delivery is asynchronous

When an event happens, Plirin writes the delivery to a durable queue and a delivery worker sends it, normally within a second. Delivery is not performed inline with the payment itself.

This matters for two reasons:

• Your endpoint being slow or down never slows down payments — not yours, and not another merchant’s. An unreachable endpoint costs its own retries and nothing else.
• A delivery you receive corresponds to an event that really committed. The delivery record is written in the same database transaction as the payment, so an event that was rolled back produces no webhook.

Delivery states

State	Meaning
queued	Accepted and waiting for the delivery worker. No attempt made yet.
pending	An attempt is in flight right now.
success	Your endpoint returned 2xx.
failed	The attempt failed and a retry is scheduled.
exhausted	All attempts used, or the endpoint was deleted or disabled.

Retry schedule

Failed deliveries are retried with exponential backoff. There are 6 attempts in total:

Attempt	Delay after the previous attempt
1	Immediate (on the next worker tick)
2	1 minute
3	5 minutes
4	30 minutes
5	2 hours
6	24 hours

After the sixth failed attempt the delivery is marked exhausted and is not retried again automatically. You can still replay it by hand.

Deduplication

Delivery is at-least-once: the same event may reach you more than once, for example if a delivery succeeds but the response is lost, or if Plirin restarts mid-delivery.

Every attempt carries a unique X-Plirin-Delivery-ID header. Record the IDs you have processed and skip repeats.

Caution

Always implement idempotent webhook handlers, keyed on X-Plirin-Delivery-ID. At-least-once delivery is a guarantee about not losing events, not a promise that each one arrives exactly once.

Replaying failed deliveries

Failed deliveries can be replayed from the Settings > Webhooks page in the dashboard. Click on a failed delivery and select Replay to re-send it to your endpoint. A replay is sent immediately rather than queued, so you get an answer while you are looking at the screen.

Monitoring

The Webhooks settings page shows:

• Recent deliveries with status (see the table above)
• Response codes from your endpoint
• Delivery timestamps and attempt counts