How to Set Up Webhooks
Webhooks send an HTTP POST with a JSON payload to your endpoint when a respondent starts or submits a survey, or refuses its terms. Use them to feed a CRM, a data warehouse or a notification service without polling.
Webhooks are an Advanced Mode tool: open Share → Webhook with Advanced Mode on.
Step 1: Add a webhook
Open Share → Webhook.
Select Add Webhook.
On the Settings tab, fill in:
- Name: a descriptive label, for example
CRM intake. - Payload URL: the
httpsendpoint that will receive the events. - Secret Token: an optional shared secret (see Step 3).
- Name: a descriptive label, for example
Choose at least one Trigger:
Trigger Fires when survey.startA respondent begins a survey session. survey.submitA respondent submits their responses. survey.terms.refusedA respondent declines the required survey terms. Leave Active on, or turn it off to keep the configuration without dispatching.
Step 2: Understand the request
Each delivery is a POST with Content-Type: application/json and a User-Agent of AccessibleData-Webhook/1.0. The payload identifies the event, the survey and the session:
{
"event": "survey.submit",
"timestamp": "<server timestamp>",
"surveyId": "<survey id>",
"isTest": false,
"context": {
"actorId": "...",
"formActorId": "...",
"buid": "...",
"uid": "...",
"campaign": "...",
"source": "..."
}
}The request times out after 10 seconds. Respond quickly with a 2xx status; do slow work asynchronously after acknowledging. A non-2xx response is recorded as a failed delivery and is not retried automatically.
Step 3: Verify the secret token
If you set a Secret Token, every request carries it in the X-A11y-Token header. On your server:
- Read
X-A11y-Token. - Compare it with the configured secret using a constant-time comparison.
- Reject the request with
401when it does not match.
Because the header is sent as-is rather than signed, use HTTPS and keep the secret out of client-side code. Rotate the secret by updating the webhook and your server together.
Step 4: Send a test event
- Open the webhook's Test tab.
- Select Send Survey Start Event, Send Survey Submit Event or Send Terms Refused Event.
- Read the result:
- HTTP status (for example
200 OKor500 Internal Server Error), - response time in milliseconds,
- response body returned by your server.
- HTTP status (for example
A test uses the same request shape but does not create a respondent session or a real survey event.
Step 5: Check deliveries
Open the Events tab for the delivery audit: timestamp, trigger, delivery status and payload for each attempt. Use it to diagnose an endpoint that intermittently fails or a trigger that never fires.
Troubleshooting
- No event arrives: confirm the webhook is active, the trigger is selected, and the survey was published after the webhook was configured. Test submissions do not dispatch live events.
- The request times out: your endpoint took longer than 10 seconds. Acknowledge first, then process.
401from your server: the secret token differs. Update both sides.- Duplicate work: a respondent can start more than once; treat
survey.startas idempotent keyed byactorId. - Terms refusals are not reported: check that the survey actually requires terms; the trigger only fires when a respondent declines them.
Related Content
- Survey Webhooks Reference: Settings, test and event tabs in detail.
- Platform API Reference: OpenAPI endpoints for survey data.
- How to Set Survey Terms: Making the terms refusal event possible.
- How to Publish and Distribute a Survey: Publishing the survey the webhook listens to.