Set up webhooks

Get real-time event notifications when responses are submitted or survey status changes.

Webhooks send events to your server when something happens in QuestionPunk. You can receive events when a response starts or completes, when a survey is published or unpublished, or when a response limit is reached. Use webhooks to trigger follow-up workflows without polling.

Last reviewed
developerwebhooksintegrationsautomation10-15 minutes to configureIntermediateDevelopersProduct teams

Before you start

Prepare a publicly accessible HTTPS endpoint that accepts POST requests. When you create the endpoint, save the returned webhook secret securely so your receiver can verify deliveries.

Steps

  1. Add a webhook endpoint

    Go to Settings > Developer > Webhooks and click + Add Endpoint. Enter a publicly accessible HTTPS URL that can receive POST requests.
  2. Choose events

    Choose the response, booking, survey, recruitment, or panel submission events your workflow needs: response.completed, response.started, response.abandoned, response.updated, response.analyzed, response.approved, response.denied, booking.scheduled, booking.canceled, payment.succeeded, payment.refunded, survey.published, survey.unpublished, survey.response_limit_reached, recruitment.started, recruitment.fulfilled, recruitment.partial, recruitment.failed, panel.submission.approved, panel.submission.rejected, panel.submission.payout_released, panel.submission.paid. Select all selects the events currently listed. To subscribe to future event types too, use * through the API.
  3. Verify request signatures

    Each delivery includes an X-QP-Signature header with the value sha256=<hex>. This is an HMAC of the raw request body. Verify it with your webhook secret to confirm the request came from QuestionPunk.

    English interface · Demo study. Use the controls described in this step.

  4. Check delivery logs

    Open Settings > Developer > Logs to review delivery history. You can see HTTP status codes and response times there to diagnose failed deliveries.

Details and limitations

Webhooks help you respond to QuestionPunk events in real time. Common uses include sending a Slack notification when a response is completed, syncing data to a CRM, or triggering an analysis pipeline.

Response events cover starts, completions, abandonment, updates, completed analysis, and the final approval or denial of a response. Booking events cover scheduled and canceled bookings. Survey events cover publishing, unpublishing, and reaching the response limit. Recruitment events track started, fulfilled, partial, and failed recruitment. Panel submission events track approvals, rejections, payout release, and payment. Choose the event that represents the action you need; a booking event is separate from a completed survey response. Survey payment events report successful and refunded Stripe payments; they are separate from panel payouts.

Webhook secrets are encrypted at rest using AES-256-GCM. Each delivery is signed with SHA-256 HMAC so your server can verify authenticity.

If a delivery fails, check the delivery log in Settings > Developer > Logs. Review the HTTP status code and response time to help diagnose the issue.

Acknowledge quickly and handle retries. Return a 2xx status within 10 seconds after accepting the event, and do slower work in your own queue. Failed deliveries can be attempted up to six times. Deduplicate by X-QP-Event-Id (also the payload’s id), not X-QP-Delivery-Attempt-Id, which changes for each attempt. A retry must not send the same reward or create the same record twice.

Signature does not match. Compute the HMAC from the original request bytes before parsing JSON; re-serializing JSON can change those bytes. Compare against the sha256= signature using a timing-safe comparison. Keep the signing secret on your server, never in browser code. If no request reaches your receiver, check HTTPS accessibility and delivery logs before changing signature verification.

Check the result

You should have a webhook endpoint saved, the right events selected, and delivery logs available to review after QuestionPunk sends events.

If something goes wrong

If deliveries fail, open Settings > Developer > Logs and check the returned HTTP status code and response time for the endpoint.