Skip to main content

Overview

Webhooks send an HTTP POST to your hook_url when subscribed events occur. Choose interview.completed, study.completed, report.ready, study.paused, study.resumed, study.stopped, participant lifecycle events, and/or study.quota_reached in event_types. Omit study_id for an account-wide webhook, or include an owned study_id to receive events for one study. The default subscription is interview.completed. Each subscribed event uses an envelope with id, type, study_id, and data. For interview.completed, data has the same public shape returned by Get Interview, including the participant, quality, messages, recording links, and screener responses.
1

Register a webhook

Call Create Webhook with the hook_url that should receive events, with optional study_id and event_types. The response includes a signing_secret — store it securely to verify signatures. Send an Idempotency-Key to recover the same response after a timeout without registering a second webhook. The same-key response can be replayed for 30 days while the webhook and secret remain current; ordinary reads hide the secret.
2

Receive interview data

Your endpoint receives a signed POST when a subscribed event occurs. The interview payload is described below; study and report events use smaller data objects.
3

Stop receiving data

Delete the webhook by its id to stop further deliveries. The URL-based delete endpoint remains available for account-wide registrations.
List and get operations return webhook IDs, scopes, event types, and URLs without revealing stored signing secrets. Use secret rotation when the original secret is lost or needs replacement; the new secret appears only in the rotation response.

Participant lifecycle events

These events are opt-in. They add no email, transcript, screener answer, or recording URL. Test interviews and panel fielding control records do not emit participant lifecycle events. Rejected screeners do not emit participant.screened. Start coverage is the voice-interview callback path; it does not imply every chat or synthetic runtime emits a start event. Quality events cover the initial completion rating, not subsequent manual rescoring. Delivery ordering is not guaranteed. Participant event IDs combine event type and persisted interview ID. Quota event IDs include the target cycle ID. Deduplicate by envelope id, independently of signature verification.

Delivery behavior

Return 2xx promptly and deduplicate using the stable event id: a timed-out delivery may have reached your receiver before it is retried. Inspect /webhooks/{webhook_id}/deliveries for status, timing, and coarse failure reasons. The history does not store payloads.

Payload

Subscribed events use {id, type, study_id, data}. For interview.completed, data is the completed interview in the same public shape as GET /interviews/{id}. The participant is nested under data.participant.
study.completed is emitted when its active target cycle reaches its target. Each newly persisted report has its own report.ready event ID.
The study.completed envelope has the same top-level fields, with a cycle ID as id and data.completed_at instead of data.report_id. A test ping uses {"type":"webhook.test","id":"webhook-id"} and contains no participant or study data. Test pings use the same signing headers and appear in delivery history. Each ping has a fresh webhook-id; the payload id still identifies the registration. Public API pause, resume, and stop calls emit study.paused, study.resumed, and study.stopped after the transition succeeds. Their data contains only study_id and the resulting fielding_status. Each transition receives a new event ID; deduplicate redeliveries by that ID. These lifecycle events currently cover the public API routes, not dashboard transitions.

Fields

Anonymous panel interviews have no identifiable participant, so participant is null for them. Internal columns (transcripts of the raw call, internal IDs, and the like) are never included — the webhook delivers exactly the public interview shape.

Authentication

Standard Webhooks

Deliveries with a signing secret include Standard Webhooks headers. Use a Standard Webhooks verifier with the raw request body and all three headers. Reject requests when verification fails before processing the payload.
Install with npm install standardwebhooks.
Use the signing_secret returned by creation or rotation. Older secrets used unpadded base64url after whsec_. To use one with a Standard Webhooks verifier, keep the prefix, convert - to + and _ to / in the suffix, then pad the suffix with = to a multiple of four characters. If an older registration has no signing secret or its secret is invalid, rotate it to get a standard secret. Deduplicate verified deliveries by webhook-id so a retry does not repeat your processing. Keep your endpoint on HTTPS and acknowledge verified events promptly.

Migrating an existing receiver

Replace any verifier that expects X-UI-Timestamp and X-UI-Signature with a Standard Webhooks verifier, including the webhook helpers shipped in SDK 1.0.0. Pass all three standard headers and the raw request body. Use a signed test ping to check your receiver before processing live events.
Store the signing_secret securely — it is shown only once, at creation. If you lose it or need to rotate it, call the secret-rotation endpoint and update your receiver with the new secret.

Managing webhooks

Use GET /api/public/v1/webhooks/ to find webhook IDs and GET /api/public/v1/webhooks/{webhook_id} to inspect one registration. Neither response includes its stored signing secret. Use POST /api/public/v1/webhooks/{webhook_id}/rotate-secret to replace a lost or compromised secret; update the receiver with the new one immediately. Use POST /api/public/v1/webhooks/{webhook_id}/test to send a signed, data-free test event. Check GET /api/public/v1/webhooks/{webhook_id}/deliveries for recent attempts (page and page_size are bounded). Delete by ID with DELETE /api/public/v1/webhooks/{webhook_id}. Repeating the delete returns 404. Use DELETE /api/public/v1/webhooks/{webhook_id} to delete a registered webhook.

Create Webhook

Register a URL, optional study scope, and event subscriptions.

Delete Webhook

Stop sending completed interviews to a registered webhook ID.