What it is for
A webhook is a message Shog sends to your server when something happens, so your system does not have to keep asking. It can say that:
- an employee was added, changed or deactivated;
- someone was enrolled, completed or failed a course, had an enrolment cancelled, or was given another attempt;
- a certificate was issued.
The message names what happened and carries IDs, not personal details. Your system then reads the record it needs through the API.
Add a destination
- Open the company, then Integrations and Webhooks.
- Choose Add destination, give it a name and your server's HTTPS address. The address cannot be changed later; add a new destination if your server moves.
- Tick the events that server needs.
- Copy the signing secret when it is shown. It is shown once.
- Set up signature checking on your server, use Send sample, then Enable the destination.
Worth knowing
A new destination starts disabled, so nothing arrives before your server is ready to check it. A company can have up to three active destinations.
Check every message
Each message carries three headers: webhook-id, webhook-timestamp and webhook-signature. Your server should sign the raw body with the destination's secret and compare, refuse a message whose timestamp is more than five minutes old, and ignore an ID it has already handled. Events and signing shows a receiver you can copy.
When your server is down
Answer with any 2xx quickly, then do the work. A message that gets no answer, or anything other than a 2xx, is tried again with growing gaps for up to 72 hours. Deliveries shows the last 30 days, each attempt and its payload, and lets you send one again.
Read next
- Connect a system with the APIGive your HR system, intranet or dashboard its own key to add staff and read training records.