Debug deliveries
Find out why a Signals webhook did not arrive or did not verify, resend it, and handle each part of a delivery.
- Complexity
- 2/5
- Clients
- Console, Node.js
- Time
- 15 minutes
When an event doesn't reach your server, the cause is in your receiver, the subscriber or the API call that set it up.
Fix receiver errorsServer-side
Signals counts any answer other than 2xx as a failed attempt. It retries a failed delivery up to 10 attempts over about 75 hours, then marks it failed.
| Symptom | Cause | Fix |
|---|---|---|
Your server answers 400 and verification fails | A body parser such as express.json() re-serialized the body, so the bytes no longer match the signature | Verify the raw body, as in the receiver |
| Verification fails on every delivery | The secret is not this subscriber's, or was rotated | Use the subscriber's current secret. After a rotation the old one signs for another 24 hours |
| Verification fails with a timestamp error | Your clock differs from the webhook-timestamp by more than your library's tolerance, 5 minutes in Standard Webhooks libraries | Sync your clock. Each retry carries a fresh timestamp, so age is never the cause |
| Attempts show no status | Signals waited 15 seconds without an answer | Answer first and process afterwards |
Attempts show a 3xx | Signals does not follow redirects | Register the final URL |
Attempts show 429 or 5xx | Your receiver is struggling | Signals holds the subscriber's other events and honours Retry-After up to 24 hours |
Attempts show 410 | 410 Gone ends the delivery and turns the endpoint off | Answer 2xx, then enable the endpoint |
| No attempt at all, and the error names a private address | A URL such as localhost resolves to a private address, so Signals refuses it | Register your public tunnel URL |
An alert.* event more than 15 minutes old is not sent: its status is expired. A redelivery is sent whatever its age.
Fix API errorsTerminal
| Status | Meaning here | Fix |
|---|---|---|
401 | The app id or secret is wrong or switched off. See UNAUTHENTICATED | Check OVOK_MANAGER_ID and OVOK_MANAGER_SECRET |
403 | The role isn't SUBSCRIBER, or the caller lacks the webhook capabilities. See FORBIDDEN | Use the Manager app, and send "role":"SUBSCRIBER" |
403 | You named episode.* while episodes are off. See FEATURE_DISABLED | Turn on episodicAlerts, or drop episode.* |
409 | The project has no tenant of its own. See SIGNALS_TENANT_NOT_OWN | Use a project with its own tenant |
409 | A reading with the same identifier was already stored. See DUPLICATE_READING | Don't resend it |
422 | A field failed validation. See VALIDATION_FAILED, WEBHOOK_REQUIRED and WEBHOOK_URL_MISSING | Read errors in the answer. Send no clientId, secret or webhookSecret |
Resend an eventConsole
Signals › Events lists every event with its delivery status: pending, delivered, failed, expired or held. Filter to failed, open a delivery to see each attempt's status, then send it again.
- 1Signals stores webhook delivery history.
- 2Review a failed attempt and send that delivery again.
POST /v1/signals/api/events/:id/redeliver does the same. A redelivery keeps the webhook-id and gets a new webhook-timestamp. When deliveries fail covers held events and disabled endpoints.
Read a deliveryServer-side
Each delivery has three parts, and each asks something of your receiver.
| Part | Holds | Handle it by |
|---|---|---|
| Headers | webhook-id, webhook-timestamp and webhook-signature, plus x-actimi-event-type and x-actimi-subscriber | Verifying the signature, then storing webhook-id and skipping an id you've seen: a retry or a redelivery repeats it |
| Envelope | type and timestamp | Routing on type |
data | The alert, episode or patient, with its own id and a version | Ignoring a version lower than one you've handled |
Answer 2xx before you do the work, and process the event from a queue. Event payloads lists every field.
Next
Last updated on