Webhooks and delivery recovery

Register a destination

POST /api/v1/{orgId}/webhooks requires webhooks:write.

{
  "name": "Facility integration",
  "url": "https://integration.example.com/facilipulse/events",
  "events": ["member.prefs_updated", "notification.sent"],
  "secret": "REPLACE_WITH_A_STRONG_RANDOM_SECRET"
}

Destinations must use public HTTPS. Private network, loopback, credential-bearing, and other unsafe targets are rejected. Always configure a secret; unsigned delivery is possible if you omit it. Store the secret securely because list responses only report hasSecret.

Allowed subscription names include facility.override_changed, facility.status_changed, area.status_changed, notification.sent, member.prefs_updated, and *. Registration support alone does not guarantee every underlying change emits an event; verify the producer workflow before depending on a specific event.

Envelope and signature

{
  "eventId": "example_event_id",
  "event": "member.prefs_updated",
  "orgId": "YOUR_ORG_ID",
  "timestamp": "2026-09-08T12:00:00.000Z",
  "data": {}
}

Payload fields inside data depend on the event. Headers include X-FacilityStatus-Event, X-FacilityStatus-Org, and X-FacilityStatus-Delivery. When a secret is configured, X-FacilityStatus-Signature is sha256= followed by the hexadecimal HMAC-SHA256 of the exact request body bytes.

Verify against the raw body before parsing, compare signatures in constant time, validate the organization, and deduplicate by event ID (and delivery ID for per-delivery tracking). There is no separate signed freshness header; use durable deduplication to resist replays while allowing legitimate delayed retries.

Delivery and recovery

Persist accepted events before returning 2xx and process them asynchronously. The sender uses an 8-second request timeout and up to five attempts for transient failures. Retried HTTP statuses include 408, 409, 425, 429, and 5xx. Other failures can become dead_letter. Ordering and exactly-once delivery are not guaranteed.

List registrations with GET /api/v1/{orgId}/webhooks. Remove one with DELETE /api/v1/{orgId}/webhooks/{webhookId}. Read delivery history at GET /api/v1/{orgId}/webhook-deliveries?limit=50 (maximum 100). Replay using POST /api/v1/{orgId}/webhook-deliveries/{deliveryId}/replay; this queues delivery again and can repeat effects if the destination is not idempotent.

Notification events describe notification workflow outcomes, not proof that every recipient read a message. Confirm individual delivery outcomes separately.