Webhooks: events, signing, retries and the delivery log
Tell your own systems when something happens (a status change, a refusal at the gate, an incident, an expiry, an overdue action), signed and retried if it fails.
2 min readLast updated
Applies to: Integrations · Administrator
A webhook sends a short message to an address you choose whenever something happens in iComply. Company admins set them up in Connections (Integrations pack).
How to add an endpoint
- Step 1: Open Company → Connections, then Add an endpoint under Webhooks.
- Step 2: Enter the Address (https) and, if you like, a Description (optional).
- Step 3: Under Events, tick the events to send.
- Step 4: Choose Add endpoint, then copy the signing secret straight away. It's shown once and never again.
The events
- subcontractor.status_changed: one of your subcontractors changed status (cleared, expiring or in review, not cleared).
- gate.refused: someone was refused at the gate or front desk (not cleared, or on the stop list).
- gate.override: a refusal was overridden and the person let in.
- incident.reported: an incident or near miss was reported.
- document.expiring: an approved document or ticket expires in 30, 14, 7 or 0 days.
- corrective_action.overdue: a corrective action went overdue (on its first overdue day).
Each message carries ids, sites, company names, dates, kinds and counts. Never people's names, incident descriptions, override reasons or the stop list's reason.
Check the signature
Each delivery has an X-IComply-Signature header: a timestamp and an HMAC-SHA256 of the timestamp and the raw body, made with your signing secret. Check it, and refuse anything more than 5 minutes old. The developer page has example code: /developers/api.
Manage an endpoint
- Step 1: In Webhooks, choose the endpoint's address.
- Step 2: Under Events, change the description or Send these events, then Save.
- Step 3: Under Controls: Switch off or Switch back on, Send a test event, Make a new signing secret (the old one stops working at once), or Remove this endpoint.
- Step 4: Read the Delivery log: each event, when it was made, the attempts, the last answer and its state (Delivered, Waiting or Failed). Choose Send again on a failed one.
What happens when a delivery fails
- Your endpoint should answer with a 2xx status within 10 seconds. Redirects aren't followed.
- Anything else is retried after 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours and 24 hours, then marked failed (7 attempts in all).
- After 15 failed attempts in a row the endpoint is switched off, waiting deliveries are marked failed, and your company admins get an email: "A webhook endpoint was switched off". Fix it, then Switch back on.
- The same event goes to the same endpoint at most once.
Limits
- https only, on port 443, and a public address: private and internal addresses are refused when you save and before every delivery.
- The delivery log shows the latest 100 deliveries.
- A test event is sent within a minute or so; nothing is sent to an endpoint that's off.