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.

SymptomCauseFix
Your server answers 400 and verification failsA body parser such as express.json() re-serialized the body, so the bytes no longer match the signatureVerify the raw body, as in the receiver
Verification fails on every deliveryThe secret is not this subscriber's, or was rotatedUse the subscriber's current secret. After a rotation the old one signs for another 24 hours
Verification fails with a timestamp errorYour clock differs from the webhook-timestamp by more than your library's tolerance, 5 minutes in Standard Webhooks librariesSync your clock. Each retry carries a fresh timestamp, so age is never the cause
Attempts show no statusSignals waited 15 seconds without an answerAnswer first and process afterwards
Attempts show a 3xxSignals does not follow redirectsRegister the final URL
Attempts show 429 or 5xxYour receiver is strugglingSignals holds the subscriber's other events and honours Retry-After up to 24 hours
Attempts show 410410 Gone ends the delivery and turns the endpoint offAnswer 2xx, then enable the endpoint
No attempt at all, and the error names a private addressA URL such as localhost resolves to a private address, so Signals refuses itRegister 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

StatusMeaning hereFix
401The app id or secret is wrong or switched off. See UNAUTHENTICATEDCheck OVOK_MANAGER_ID and OVOK_MANAGER_SECRET
403The role isn't SUBSCRIBER, or the caller lacks the webhook capabilities. See FORBIDDENUse the Manager app, and send "role":"SUBSCRIBER"
403You named episode.* while episodes are off. See FEATURE_DISABLEDTurn on episodicAlerts, or drop episode.*
409The project has no tenant of its own. See SIGNALS_TENANT_NOT_OWNUse a project with its own tenant
409A reading with the same identifier was already stored. See DUPLICATE_READINGDon't resend it
422A field failed validation. See VALIDATION_FAILED, WEBHOOK_REQUIRED and WEBHOOK_URL_MISSINGRead 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.

  1. 1Signals stores webhook delivery history.
  2. 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.

PartHoldsHandle it by
Headerswebhook-id, webhook-timestamp and webhook-signature, plus x-actimi-event-type and x-actimi-subscriberVerifying the signature, then storing webhook-id and skipping an id you've seen: a retry or a redelivery repeats it
Envelopetype and timestampRouting on type
dataThe alert, episode or patient, with its own id and a versionIgnoring 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

Create a patient.

Last updated on

On this page