Webhooks
Published
Have Survtapp POST to your own URL the moment a response arrives — the events that really fire, the signature to check, and what happens when your server is down.
How do I get Survtapp to notify my own server?
Add a webhook. Go to Settings, then Webhooks, click Add Webhook, enter your https endpoint, tick the events you want and copy the signing secret — shown only once. Six events are sent: Response Created, Response Completed, Form Published, Form Unpublished, Contact Created and Contact Updated — the two contact events only when a single contact is added or edited, never on an import, a form capture or an integration sync. Answer with a 2xx within 10 seconds; a failed delivery is never retried. Verify the X-Survtapp-Signature header against the raw body before trusting a payload.
A webhook tells your own server the moment something happens in Survtapp. Survtapp sends a POST request with a JSON body to a URL you choose, signed so you can prove it came from us.
Only the account owner can open Settings → Webhooks. Admins, managers, agents and read-only users do not see the page.
Adding a webhook
- Go to Settings → Webhooks and click Add Webhook.
- Put your endpoint in Endpoint URL — it must be a full https address. Survtapp sends a POST request to this URL when events occur.
- Under Events to Subscribe, tick the events you want. At least one is required.
- Click Create Webhook, then copy the Signing Secret. This is the only time you will see it.
Which events actually arrive
The picker offers six events, and every one of them really is sent:
- Response Created — a response is created on submit, from any collection channel: a public form, the dashboard, or a mobile device syncing.
- Response Completed — a response is submitted or completed, from any collection channel.
- Form Published — a form is published from its Publish action.
- Form Unpublished — a published form is taken offline from its Publish action.
- Contact Created — a contact is added by hand on the Contacts page, or created through the API.
- Contact Updated — a contact is edited on the Contacts page, or updated through the API.
Read the two contact events narrowly: they fire when a single contact is added or edited by hand, and nothing else fires them. Four other things put a contact in your account silently — a CSV import, a contact captured by someone filling in a public form, a contact captured while a response is submitted from the dashboard or the API, and a contact brought in by an integration sync, whether that is a GoHighLevel or HubSpot pull or a customer arriving from Lightspeed. None of them sends Contact Created or Contact Updated. If you need to know about those, poll your contacts or watch the response events instead.
The two form events are just as narrow. They come only from the Publish and Unpublish buttons on the form itself. Changing a form’s status any other way sends nothing: that includes the API, and it includes an AI assistant moving a form back to draft or archiving it through the connector. If you need to know a form has gone offline however it happened, read its status rather than waiting for a webhook.
Survtapp accepts only those six when you create a webhook and when you edit one, so you cannot subscribe to something that never arrives. If you set a webhook up before this list settled it may still hold an event that is no longer offered — a waiver or checklist event, for instance. It keeps showing in your list, it never fires, and you can still switch it off; to clear it for good, edit the webhook and pick from the current six. For a waiver or a checklist signal, use Response Completed: a signed waiver and a finished checklist are both responses.
What a delivery looks like
A POST with a JSON body carrying the event name, the send timestamp and a data object. Inside data, each thing the event concerns sits under its own key — a response event carries data.response and data.form. Each answer in data.response.answers has a questionId and a value, and the value’s type follows the question: a string, a number, true or false, an ISO date, or a list for a multi-select.
- X-Survtapp-Event — the event name.
- X-Survtapp-Timestamp — the send time, ISO 8601.
- X-Survtapp-Signature — an HMAC-SHA256 of the raw request body, using your signing secret, written as sha256= followed by the hex digest.
Always check the signature before you trust a payload, and check it against the raw body exactly as received. The full reference, with the complete sample payload and verification code, is at /docs/webhooks.
Timeouts, failures and retries
Return any 2xx status within 10 seconds. Anything else — a 4xx, a 5xx, a redirect, or taking longer than 10 seconds — is recorded as a failed delivery and is not retried. There is no automatic retry and no queue: a delivery your server misses is gone. So acknowledge quickly and do the real work afterwards, and if your endpoint is going down, plan to reconcile from an export rather than waiting for a resend.
The list shows each webhook as Active or Inactive with the events it is subscribed to and when it was last triggered. Use the toggle to pause one without losing its secret, and delete it to remove it for good. There is no delivery log in your dashboard, so you cannot look up an individual delivery or replay one — your own server’s logs are the record.
When nothing arrives
- Check the event is one of the five that are actually sent.
- Check the webhook is Active.
- Check your endpoint answers a POST with a 2xx inside 10 seconds, from the public internet — a localhost or private address can never be reached.
- Check your signature check against the raw body. Parsing and re-serialising the JSON first changes the bytes and the signature will not match.