Sample environment. Data is public, visible to other visitors, and erased nightly — do not enter real names, injuries or personal information.
MMigna

Webhooks

Company tierIn the app: /webhooks

Webhooks send a signed HTTPS request to an address you give us whenever one of the events you choose happens, so a chat channel, a ticketing system or your own database hears about it straight away. Each request carries the record in the same shape the REST API returns, and we retry a failed delivery for nearly two days before giving up.

1.Add an endpoint (admin)

  1. Open Webhooks under Admin Settings.
  2. Give the endpoint a name and the https:// address that will receive the events. It must be reachable on the public internet.
  3. Tick the events to send: an incident is reported, a safety observation is reported, a corrective action is raised, a corrective action is completed or verified, a site audit is saved, an equipment inspection fails, a training record is added, a change is approved, a change is implemented, a permit is approved, a permit is closed out. Only events for modules your company has on are listed.
  4. Press Add Endpoint and copy the signing secret. It starts with whsec_ and is shown only now.
  5. Press Send Test Event to send a ping and see what your endpoint answered.

2.Receive an event

  1. Each event is a POST with a JSON body: id (the delivery's id), event (such as incident.created), createdAt, and data, the record as GET /api/v1/<resource>/<id> would return it.
  2. Headers: Migna-Event names the event, Migna-Delivery repeats the id, and Migna-Signature reads t=<unix time>,v1=<signature>.
  3. Answer with any 2xx status within 10 seconds. Do slow work after answering. A redirect counts as a failure, since we do not follow them.
  4. A delivery can arrive more than once, for example after a retry that did reach you. Use the id to ignore one you have already handled.

3.Check the signature

  1. Take t and v1 from the Migna-Signature header.
  2. Compute an HMAC-SHA256 of the text t, a full stop, then the raw request body, using the signing secret as the key, and write it as hexadecimal.
  3. Accept the request only if your result equals v1, compared in constant time, and t is within five minutes of now. Otherwise answer 400.
  4. If the secret leaks, press Rotate Secret. Deliveries are signed with the new secret straight away.

4.Follow up on failures (admin)

  1. Press Show Deliveries on an endpoint for its last 25 deliveries with the HTTP status or error.
  2. A failed attempt is tried again after 15 minutes, an hour, 4 hours, 12 hours and a day: six attempts in all. Press Send Again to try one now.
  3. An endpoint whose deliveries fail every attempt 15 times in a row is switched off, with the reason shown. Fix the receiver and press Turn On.
  4. We keep deliveries for 30 days. Adding, changing, rotating and deleting endpoints is recorded in the Activity Log.

5.Subscribe through the API (integrations)

  1. An integration that subscribes itself, such as a Zapier integration, needs an API key with the Zapier Webhooks permission. It can subscribe only to events about records the key can read.
  2. POST /api/v1/hooks with a JSON body of url (the https:// address to send to) and event (such as incident.created). The answer carries the subscription's id and its signing secret.
  3. GET /api/v1/hooks lists the key's subscriptions and the events it may subscribe to. DELETE /api/v1/hooks/<id> unsubscribes. A key sees and removes only its own, and holds at most 50.
  4. Deliveries are the same signed requests described above. If the receiving address answers 410 Gone, we delete the subscription.
  5. Each subscription is listed on the Webhooks page, marked with the key that made it. An admin can turn it off or delete it there; revoking the key deletes them all.

Common questions

What is in the data?
The same fields as the REST API: never files, photos, signatures, contact details or anything medical, and a privacy case without the person's name. To read more, call the REST API with the record's id.
Which changes send an event?
Incidents and observations reported in the app, from a QR code or with the assistant; corrective actions however they are raised (on the page, from another module, with an incident report, from a maturity gap, by importing a gap analysis or with the assistant), and closed on the page or with the assistant; audits and inspections saved in the app or uploaded from a phone that was offline; training records added on the Training page or by a QR course; changes approved or implemented; and permits approved or closed out.
Why was my address refused?
It must start with https:// and point at the public internet. We refuse addresses on private networks, both when you add them and when we send, so a webhook cannot be used to reach something inside our own network.

Read next

← REST APICustom Reports →

Something here does not match what you see in the app? Tell us from Help & Support inside the app, or email info@mignasafetysolutions.com. We correct the guide rather than let it drift.

Webhooks — Migna User Guide