Skip to main content

Partner API: Webhooks

Receive document, employee and Auto Policy Update events at your endpoint, with signed at-least-once delivery.

Instead of having AirMason email employees and admins, you can receive every event as an HTTP POST to a URL you control and drive your own notifications. Webhooks are configured per organization.

Configure

PUT /organizations/{orgId}/webhook | Access token

{
  "url": "https://hooks.acme.com/airmason",
  "events": ["*"],
  "disableAirMasonEmails": true
}
{
  "url": "https://hooks.acme.com/airmason",
  "events": ["*"],
  "disableAirMasonEmails": true,
  "secret": "whsec_7Hq…",
  "createdAt": "2026-09-15T14:00:00.000Z"
}

  • events is a list of event types, or ["*"] for everything.

  • disableAirMasonEmails: true suppresses all AirMason-sent employee and admin emails (welcome, assignment, reminders, publish notices) for this organization: you become responsible for notifying people using the event payloads, which include AirMason's templated title and body for each notification.

  • secret is returned once; use it to verify signatures.
    ​POST …/webhook/rotate-secret issues a new one (the old one stays valid for 24 hours).

Delivery

Each event is delivered as a POST with a JSON body and these headers:

POST /airmason HTTP/1.1
Content-Type: application/json
X-AirMason-Event: employee.signed
X-AirMason-Delivery-Id: dlv_01J8…
X-AirMason-Timestamp: 1758029400
X-AirMason-Signature: v1=5f3a…

The signature is HMAC-SHA256(secret, "<timestamp>.<raw body>"), hex-encoded. Reject requests whose signature doesn't match.

Delivery guarantees:

  • At-least-once. We consider an event delivered when your endpoint returns any 2xx within 10 seconds. Anything else (non-2xx, timeout, connection error) is retried.

  • Retries use exponential backoff over roughly 24 hours: 1 min, 5 min, 30 min, 2 h, 6 h, 12 h, then 24 h after the original attempt. After the final attempt the delivery is marked failed and an alert email is sent to your account's technical contact (this email is never suppressed).

  • Idempotency. Retries reuse the same X-AirMason-Delivery-Id. De-duplicate on it: you may occasionally receive the same delivery twice.

  • Ordering is not guaranteed across events; use occurredAt in the payload.

  • Granularity. Employee-level events are sent one per employee (e.g. publishing a handbook to 400 people produces 400 employee.handbook_assigned events), so each carries that person's own activation or handbook link.

GET /organizations/{orgId}/webhook/deliveries?status=failed lists recent deliveries and their attempts;

POST /organizations/{orgId}/webhook/deliveries/{deliveryId}/redeliver replays one.

Payload shape

{
  "id": "evt_01J8…",
  "type": "employee.signed",
  "occurredAt": "2026-01-16T09:14:37.000Z",
  "organization": { "id": "1f2a…", "externalId": "acme-eu" },
  "notification": {
    "title": "Sam Okafor signed Employee Handbook 2026",
    "body": "Sam Okafor (sam.okafor@acme.com) signed version 7 of Employee Handbook 2026 on 16 Jan 2026."
  },
  "data": { … }
}

notification.title and notification.body are the templated texts AirMason would have used in its own email for this event, so you can use them or replace them with your own copy. data varies by event type.

Event types

Document (handbook) events

Type

Sent when

Key data fields

document.created

A handbook is created

handbook { id, name }

document.launched

A handbook is launched (made available to employees for the first time)

handbook, url

document.published

A version is published

handbook, version, signatureRequired, acknowledgementRequired, publishType — manual, apu_auto (published automatically by Auto Policy Update), or auto_republish (linked content re-published)

Employee events (one per employee)

Type

Sent when

Key data fields

employee.created

An employee is created (via API, import or HRIS)

employee { id, employeeId, email, firstName, lastName }, activationLink (single-use, valid 30 days), activationLinkExpiresAt

employee.handbook_assigned

An employee is given access to a handbook (directly, via group, or on publish)

employee, handbook, version, url, signatureRequired

employee.signed

The employee signs

employee, handbook, version, signedAt

employee.acknowledged

The employee acknowledges

employee, handbook, version, acknowledgedAt

employee.signature_reminder

A signature/acknowledgement reminder is due (per the handbook's reminder schedule)

employee, handbook, version, url, daysOutstanding, reminderNumber

Auto Policy Update events (per handbook)

Type

Sent when

Key data fields

apu.policy_added

A new policy applicable to the organization's purchased regions becomes available for a handbook

handbook, policy { id, title, regions }, summary

apu.policy_updated

Auto Policy Update applies an update to a handbook

handbook, policy, summary, changes[], publishedVersion (set if auto-published)

Partner API documentation:

Related Articles
Did this answer your question?