A webhook automatically sends submission data to an external system as soon as an employee submits your form, so nobody needs to export, import, or re-enter it by hand. Paired with an integration service that your technical team builds, a webhook can trigger a workflow in another system. For example, an incident report, HR request, or expense reimbursement form can feed directly into your ticketing, HR, or expense system.
Every webhook includes an authentication secret, so the receiving system can confirm that a request came from your Staffbase environment. To decide between a webhook, email notifications, and a recipient question, see Choosing How to Route Submission Data.
How the Webhook Works
One submission triggers one webhook event. Staffbase sends the event as a POST request with a JSON body to your HTTPS endpoint. The payload contains the response data and any metadata you have chosen to collect from user profile fields, including system fields and fields custom to your organization.
If a delivery fails, Staffbase retries the request to your endpoint.
To add a webhook to a form, see Using the Form Settings. After adding it, select the three dots next to the webhook to test, edit, or delete it:
- Deliveries: Select Send test to send a test event. The delivery ID and the response status code display. Test deliveries are marked as Test.
- Edit: Change the webhook URL, or copy or regenerate the secret. After regenerating a secret, keep the previous secret and its key ID until older deliveries have finished, because retries of those events still use the old secret.
- Delete: Remove the webhook. A warning asks you to confirm.
Understanding the Webhook Payload
The JSON payload carries the following information:
- Form installation ID: The unique identifier of your form. To find it in the Studio, open the actions menu of the form and select Copy link. The ID is the last part of the URL:
https://<your-environment>/content/staffbase.forms/<form-installation-ID> - Form title: The name of the form. The title is not a unique identifier.
- Submission ID: The unique identifier of a submission. Every submission has a different value, even when the same employee submits multiple times.
- Respondent data: The user profile information collected with the response. By default, this is the first and last name. You can collect additional profile fields in the form settings under Respondent Data. If the form uses confidential responses, no user information is included.
- Answers: The responses to the answered questions. Each answer includes
questionIdandquestionLabel. If you configure a question key, the answer also includesquestionKey.
Configuring a Question Key
A question key makes the payload easier to read and to map in the receiving system. A question key must start with a lowercase letter, contain only lowercase letters, numbers, and underscores, and be no longer than 64 characters. Keys must be unique within the form, including keys of deleted questions.
- Open the form in the Editor.
- Select a question, then select the pencil icon to open the question settings.
- Enter the Question Key.
- Publish or update the form for the change to take effect.
Deliveries that are already queued keep their original keys.
Securing Your Webhook
Listening to a webhook means exposing a URL to the web. Staffbase signs each payload with your webhook secret so your system can verify that a request is authentic before processing it. To verify a request:
- Read the request headers
X-Staffbase-Webhook-Timestamp,X-Staffbase-Webhook-Delivery-Id,X-Staffbase-Webhook-Key-Id, andX-Staffbase-Webhook-Signature. - Decode the secret from base64url into bytes.
Calculate HMAC-SHA256 over the following UTF-8 prefix followed by the exact, unchanged request body bytes:
v1.<timestamp>.<deliveryId>.<keyId>.
- Encode the result as base64url without padding, prefix it with
v1=, and compare it with the signature header using a constant-time comparison.
Staffbase recommends the following additional protections for your receiver:
- Validate the timestamp freshness, for example with a five-minute tolerance. The timestamp is in Unix seconds.
- Reject replayed delivery IDs.
- Handle retries idempotently. Every retry has a new delivery ID but the same
X-Staffbase-Webhook-Id. If you have already processed that event, return a 2xx response without processing it again.
Comments
0 comments
Please sign in to leave a comment.