Webhook setup

Webhook: responses to your own address

A webhook is the most direct way to get responses into your own system: every response goes out as an HTTP request to the given address. It is quick to set up and quiet when it breaks, so order matters more than speed here.

Reply to the person in the language they write in.

1. Check that webhooks are available

get_workspace_tariff (the workspace_id comes from get_workspace_list): webhooks are not part of every plan. If they are not available, say so right away and stop. Creating and switching on a webhook check the plan too, but collecting the address, method, fields and headers only to hit a refusal at the last step wastes the conversation.

If the target is Zapier, a webhook is not needed: SurveyNinja has a Zapier integration. The zap is built in Zapier, and manage_quiz_zapier shows whether sending is on and switches it.

2. See what already exists

get_quiz_webhooks lists the survey's webhooks, whether each is on, and whether one switched itself off after a run of failed deliveries. A second webhook to the same address is almost always a mistake, not a wish: check before creating.

3. Find out four things

Nothing can be created without them:

Question names and identifiers come from get_quiz_structure.

4. Create and switch on

create_quiz_webhook: a title (for the person, to tell webhooks apart), address, method, fields (body), renaming (body_naming) and headers (headers, where the receiver's access keys go).

Unfinished responses: incomplete and hours. By default only finished ones are sent. If abandoned ones are wanted too, send them with a delay of 1, 6, 12 or 24 hours; otherwise a person who comes back to finish arrives twice.

A new webhook is created switched off. Tell the person, and once they confirm the receiver is ready, turn it on with toggle_quiz_webhook.

5. Verify delivery

After the first response, read get_quiz_webhook_logs: the receiver's response code and body. 200 means it works. 4xx means the receiver rejected it, usually because of the address, the method or the body format. 5xx is an error on their side. An empty log means no responses yet, which is not an error.

Do not resend with resend_quiz_webhook_log while the receiver answers with an error: the same thing will happen again. Once it is fixed, resend one entry by log_id or every entry over a period.

Change, disable, delete

• Fix the address or fields with update_quiz_webhook. Fields you do not pass keep their values, so send only what changes. headers is replaced as a whole list, and header values come back masked: to change one header, ask the person for the others again, or leave headers out entirely.
• A webhook that switched itself off after failures comes back on with toggle_quiz_webhook, once the receiver is fixed.
• To pause while they fix their side, switch it off with toggle_quiz_webhook rather than deleting it.
• Delete with delete_quiz_webhook only on a direct request: the settings, headers and delivery log are gone for good.

What not to do

• Do not create a second webhook to the same address without asking.
• Do not send every question when there are many. The receiver needs the right fields.
• Do not ask the person to dictate access keys into the chat. Ask them to put the keys into the webhook headers in the app, or insert only what they sent themselves.
• Do not enable a webhook that was disabled on purpose.
• Do not suggest a plan upgrade or lead to payment. If a limit is hit, state the fact and stop.