Webhook (HTTP callback)

What is a webhook

A webhook is an automatic HTTP request that one service sends to a URL you choose when an event happens. In surveys the event is usually a new response, and the request carries the answers to your CRM, backend or automation tool.

The difference from an API is direction. With an API your system asks for data. With a webhook the data comes to you by itself, so you don't have to check for new responses on a schedule.

How it works in SurveyNinja

• Webhooks are available on the Basic plan and higher. You add one on the survey's Integrations tab.
• Each completed response goes to your Call Back URL as a POST, PUT, PATCH or GET request with a JSON body.
• You can add custom headers, for example an authorization token, choose which questions to send and give them short parameter names.
• On plans that save incomplete responses (Standard and higher), a webhook can also send them every 1, 6, 12 or 24 hours.
• The log shows every delivery with your server's reply. From there you send a test request and retry failed ones.

Setup and the request format: Webhooks. If data stops arriving, see Why aren't responses reaching Google Sheets, webhooks or Telegram?

Common mistakes

• A new webhook is saved turned off. Turn on its switch, or nothing is sent.
• The URL must be a public address. Local and internal addresses are rejected.
• Your server should reply with a 2xx code within 30 seconds. Return the code first and process the data after that.
• After 20 failures in a row, or 5 in a row with a 4xx reply, SurveyNinja turns the webhook off. Fix the receiver, turn it back on and resend the failed requests from the log.