Webhooks

Webhooks deliver real-time HTTP callbacks when survey events occur. This is the recommended way to react to completions — for example, updating a patient record in your HIS when a satisfaction survey is submitted.

For full webhook configuration details, payload format, and signature verification, see the Survey Webhooks documentation.

Quick Setup via API

Create a Webhook

Endpoint: POST /api/surveys/{surveyId}/webhooks

{
  "surveyId": "SURVEY_UUID",
  "name": "Patient Survey Completion",
  "url": "https://your-system.example.com/webhooks/survey-complete",
  "events": ["survey.response_completed"],
  "secret": "your-webhook-secret",
  "isActive": true
}

Field	Type	Required	Description
name	string	Yes	Webhook name
url	string	Yes	HTTPS endpoint to receive callbacks
events	string[]	Yes	Event types to subscribe to
secret	string	No	Shared secret for HMAC-SHA256 signature verification
isActive	boolean	No	Enable/disable (default: true)

Manage Webhooks

Action	Method	Endpoint
List	GET	/api/surveys/{surveyId}/webhooks
Get	GET	/api/surveys/{surveyId}/webhooks/{id}
Update	PATCH	/api/surveys/{surveyId}/webhooks/{id}
Delete	DELETE	/api/surveys/{surveyId}/webhooks/{id}
Test	POST	/api/surveys/{surveyId}/webhooks/{id}/test
List deliveries	GET	/api/surveys/{surveyId}/webhooks/{id}/deliveries
Retry delivery	POST	/api/surveys/{surveyId}/webhooks/{id}/deliveries/{deliveryId}/retry

Integration Pattern

A common pattern combining the programmatic API with webhooks:

1. Create contacts via POST /api/directory/contacts/upsert
2. Send survey via POST /api/surveys/{id}/distributions/quick
3. Register webhook for survey.response_completed
4. Receive callback when the contact completes the survey
5. Optionally poll GET /api/surveys/{id}/responses/bulk-status for contacts that haven’t responded yet