Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.insito.app/llms.txt

Use this file to discover all available pages before exploring further.

The webhook integration sends a POST request to a URL you control every time a response is submitted. Use it to fan responses out to your data warehouse, CRM, support system, or anywhere else.

​
Setup

1

Open webhook settings

admin.insito.app → Settings → Integrations → Webhook.
2

Add your endpoint

Paste the URL Insito should POST to (e.g. https://api.your-domain.com/webhooks/insito). Must be HTTPS.
3

Copy your signing secret

Insito generates a secret on save. Copy it — you’ll need it to verify incoming requests. The secret is shown once; reset it any time via Reset signing secret.
4

Activate

Toggle the webhook on. Insito sends a test event right away — payload type webhook.test — so you can verify your endpoint is live before real responses start flowing.

​
Payload shape

{
  "type": "response.created",
  "projectId": "uuid",
  "surveyId": "uuid",
  "responseId": "uuid",
  "createdAt": "2026-05-21T18:41:00Z",
  "respondent": {
    "userId": "your-user-id",
    "platform": "ios",
    "appVersion": "2.7.0",
    "metadata": { "plan": "pro" }
  },
  "answers": [
    { "questionId": "uuid", "type": "nps", "value": 9 },
    { "questionId": "uuid", "type": "open_text", "value": "Love it!" }
  ]
}

​
Verifying signatures

Insito signs each request with HMAC-SHA256. The signature lands in the X-Insito-Signature header. Verify before trusting the body. 
import crypto from "node:crypto";

function verify(req: Request, signingSecret: string): boolean {
  const sig = req.headers.get("X-Insito-Signature");
  if (!sig) return false;
  const expected = crypto
    .createHmac("sha256", signingSecret)
    .update(req.body)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(sig, "hex"),
    Buffer.from(expected, "hex"),
  );
}
Always use crypto.timingSafeEqual (or equivalent) to compare signatures. Naïve === comparison leaks timing information that could be used to forge signatures.

​
Retries

Insito treats any 2xx response as success. Anything else triggers an exponential-backoff retry:
AttemptDelay from previous
1 (initial)—
21 min
35 min
430 min
5 (final)2 hours
After the 5th failure, the event is moved to the dead letter queue and your dashboard shows a banner. You can manually retry from Settings → Integrations → Webhook → Failed deliveries.

​
Event types

TypeWhen
webhook.testWhen you connect or re-enable the webhook. Body is a dummy response.
response.createdA user submitted a response. Most common event.
response.created.replayManual replay from the dashboard (after fixing your endpoint).

​
Headers

HeaderValue
Content-Typeapplication/json
User-AgentInsito-Webhooks/1.0
X-Insito-SignatureHMAC-SHA256 hex digest of the body
X-Insito-EventEvent type (response.created, etc.)
X-Insito-DeliveryUnique delivery ID; idempotency-safe to use as a dedupe key

​
Troubleshooting

SymptomLikely cause
Endpoint receives test, but not real eventsWebhook is per-organization but per-survey toggle is off. Check Survey → Settings → Integrations.
Signature verification always failsMake sure you’re hashing the raw body, not the parsed JSON. JSON.stringify reorders keys.
Receiving duplicatesUse X-Insito-Delivery as a dedupe key — retries reuse the same ID.