Send events with webhooks

Webhooks send FaciliPulse events to software you control. Choose them when Slack or Zapier cannot express the workflow, or when you need a durable connection to an internal service.

Before you begin

Your destination must be a publicly reachable HTTPS URL. FaciliPulse rejects loopback, private-network, credential-bearing, and other unsafe destinations. Build the receiver so it can preserve the raw request body, return a quick 2xx response, and process the event asynchronously.

You will need an API credential with webhooks:write to create or remove a destination. Follow API authentication for credential handling.

Create a destination

From the Integrations workspace, create a webhook with:

• a recognizable destination name;
• the public HTTPS URL;
• one or more event names; and
• a long, randomly generated signing secret.

Use separate destinations and secrets for development and production. Subscribe only to events the receiver needs. The wildcard * is convenient for exploration but usually too broad for production.

Supported registration names include facility.override_changed, facility.status_changed, area.status_changed, notification.sent, member.prefs_updated, and *. Registration support does not guarantee that every product workflow currently emits every named event, so test the producer action you plan to depend on.

Verify every request

When a secret is configured, FaciliPulse signs the exact request body with HMAC-SHA256. The X-FacilityStatus-Signature header begins with sha256=. Verify the signature against the raw bytes before parsing JSON, compare it in constant time, and reject a mismatched signature.

Also validate:

• the orgId belongs to the expected organization;
• the event is one your service accepts;
• the payload shape before using any field; and
• the eventId has not already been processed.

The event envelope is described with runnable examples in Webhooks and delivery recovery.

Respond and process safely

Persist the accepted event, then return a 2xx response promptly. Do slow work—sending messages, updating another system, or calling an AI service—after acknowledgement. Do not depend on delivery order, and make side effects idempotent because retries can repeat an event.

FaciliPulse uses an eight-second request timeout and retries transient failures, including 408, 409, 425, 429, and 5xx responses. Delivery can move to dead_letter after retry attempts are exhausted.

Monitor and recover

The Integrations workspace includes webhook delivery history. Review the event, response status, attempt count, and error before replaying a failed delivery. Replay can repeat a side effect, so first confirm the receiver uses eventId or a comparable idempotency key.

Use a 2xx only after the event is safely accepted. Return 4xx for a permanently invalid request and 5xx when a temporary receiver failure should be retried. Avoid redirect responses; configure the final destination URL directly.

Security checklist

• Store signing secrets in a secret manager, not source control.
• Never log full credentials, authorization headers, or sensitive payload fields.
• Rotate a secret if it is exposed and update both sides together.
• Restrict the receiver to the smallest necessary downstream permissions.
• Keep TLS certificates valid and monitor expiry.
• Alert on repeated failures and growing processing queues.

For endpoint paths, headers, example envelopes, signature details, and replay endpoints, continue to the developer webhook guide.