Every attempt Booklink makes to reach your endpoint is recorded. The Deliveries view on each endpoint shows what was sent, what your server answered, and lets you replay anything that failed.
What counts as success
Your endpoint must answer with a 2xx status code within 10 seconds. Anything else is a failure: a 4xx, a 5xx, a redirect, a timeout, a TLS error, or a DNS failure.
Answer first, work later. Acknowledge the request as soon as you have stored the payload, and do your slow processing in a background job. A handler that calls three other APIs before responding will eventually breach the 10 second timeout and start failing deliveries.
Retries
A failed attempt is retried automatically: up to 8 attempts in total, with exponential backoff spread over roughly 24 hours. That gives a short outage on your side plenty of room to recover on its own.
After the eighth attempt the delivery is marked failed and no longer retried automatically. You can still replay it by hand from the Deliveries list.
Retries mean duplicates
If your server processes a request but the response never gets back to Booklink, the same event is delivered again. Store the envelopeid and ignore any event id you have already handled.Reading the delivery log
Click Deliveries on an endpoint to expand its 50 most recent deliveries, newest first.
| Column | What it tells you |
|---|---|
| Event | The event type that was sent. |
| Status | pending while attempts remain, success once your server answered 2xx, failed once attempts ran out. |
| Code | The HTTP status your server returned. A dash means Booklink never got a response at all, usually a timeout or connection error. |
| Attempts | How many times this delivery has been tried. |
| When | The time of the most recent attempt. |
Deliveries are kept for 30 days and then removed automatically.
Redelivering by hand
Failed deliveries show a Redeliver button. Clicking it queues another attempt with the exact same body, including the original event id and created time. Only the signature header is new, because it is generated at send time.
This is what you use after fixing a bug or a deploy outage. Only failed deliveries can be redelivered: a pending one is already queued, and a successful one has nothing left to do.
Auto-disabled endpoints
If 20 deliveries in a row exhaust all their attempts and fail, Booklink switches the endpoint off and marks it Auto-disabled. An email goes to your business email address so you know it happened.
While an endpoint is auto-disabled, new events are not queued for it at all. Any single successful delivery resets the failure streak, so this only triggers when an endpoint has been broken for a sustained period.
Bringing an auto-disabled endpoint back
- 1
Fix the underlying problem
Check the Code and Attempts columns in the delivery log first. A run of401or403usually means a signature mismatch, a run of404means the URL moved, a dash means Booklink could not reach the host at all, and500means your handler is throwing. - 2
Open Edit on the endpoint
Correct the URL if it changed, then switch the Active toggle back on and save. This clears the auto-disabled state and resets the failure streak. - 3
Send a test ping
Click Test and confirm you get a 2xx back before relying on it again. - 4
Replay what you missed
Expand Deliveries and redeliver the failed entries you still care about. Events that were never queued while the endpoint was disabled cannot be recovered, so reconcile those from the Calendar or Reports pages.
Common problems
- Every delivery shows a dash in the Code column
- Booklink never reached your server. Check that the domain resolves publicly, that the TLS certificate is valid, and that no firewall is blocking the request.
- Signature checks fail on every request
- You are almost certainly hashing a re-serialised body instead of the raw bytes, or using an old secret after a regenerate. See verifying signatures.
- Deliveries succeed but nothing happens in your system
- Your handler is returning 2xx before it finishes, and the work afterwards is failing silently. Add logging on your side.
- Timeouts under load
- Store the payload and return 200 straight away, then process it in a queue.
- Some events never arrive
- Open Edit and check the event is actually ticked on that endpoint. Also confirm your subscription is still on Pro, since webhooks stop being sent otherwise.