Overview of Outbound Webhooks

Outbound Webhooks is an event-driven integration mechanism in Staffbase that sends POST notifications to an external endpoint whenever a specific event occurs within the platform. Rather than polling the Staffbase REST API for changes, receiving systems subscribe to individual event types and receive a delivery the moment a matching event fires. Each webhook is registered and managed by an administrator in Staffbase Studio and carries a signed payload to a configured HTTPS endpoint.

When a subscribed event occurs in Staffbase, the following delivery flow is initiated:

1. A matching event occurs within the Staffbase platform.
2. Staffbase constructs a JSON payload describing the event, including the event type, a timestamp, and a data object containing relevant resource identifiers.
3. Staffbase signs the payload using the webhook’s signing secret.
4. Staffbase sends an HTTP POST request containing the signed payload to the registered HTTPS endpoint.
5. The receiving system validates the signature against the shared signing secret, processes the payload, and returns an HTTP response.
6. Staffbase records the delivery outcome, including the HTTP response code, in the webhook’s delivery history.

A webhook subscription defines which events Staffbase sends to an external system and where those events are delivered.

When an administrator creates a webhook subscription in Staffbase Studio, they specify:

• One or more Staffbase event types
• The HTTPS endpoint that receives the deliveries
• A signing secret

Multiple event types can be combined in a single subscription, which reduces the number of webhook registrations required.

For example, an external HR system could subscribe to user-related events so that it receives notifications when a user account is updated or deleted in Staffbase.

Each webhook has a signing secret that the receiving endpoint uses to verify that incoming deliveries originated from Staffbase. The signing secret is established when the webhook is created. Staffbase can generate the secret automatically, or the administrator can provide one. The secret is displayed when the webhook is created, so that it can be configured in the receiving system.

Outbound Webhooks uses a push delivery model. Staffbase sends each event directly to the registered Target URL and does not store events for later retrieval through the REST API.

Before creating a webhook subscription, make sure your receiving system has a webhook listener configured. The listener must:

• Use an HTTPS endpoint that accepts HTTP POST requests.
• Verify the signature of each webhook payload.
• Return an HTTP 2xx status code to acknowledge successful receipt.

Staffbase signs the exact JSON request body with the subscription’s signing secret using .

The signature is calculated over the Unix timestamp and the exact request body:

<timestamp>.<body bytes>

Staffbase sends the timestamp and signature in the Webhook-Signature HTTP header:

t=<timestamp>,v1=<hex signature>

The timestamp is expressed in Unix seconds.

To verify a delivery, the receiving system should:

1. Extract the timestamp and v1 signature from the Webhook-Signature header.
2. Use the subscription’s signing secret to calculate the HMAC-SHA256 signature over <timestamp>.<raw request body>.
3. Compare the calculated signature with the v1 signature.
4. Process the payload only if the signatures match.

• Manage Outbound Webhooks
• Outbound Webhook Event Types