Generic Webhooks integration¶

The Generic Webhooks integration sends feedback and survey events from InstantFeedback to any HTTPS endpoint you control, as JSON over HTTP POST. Use it to feed your CRM, data warehouse, automation platform, or your own code. Once it is set up, you get:

• A request to your endpoint for every feedback request sent, reminder sent, grade received, comment received, survey started, and survey completed.
• Several webhooks per account, each subscribed to the events you choose, with an account-wide default and per-campaign overrides.
• Selected custom fields included in the payload, chosen per campaign.
• Every request signed with an HMAC-SHA256 signature, so your endpoint can verify that it came from InstantFeedback.
• Automatic retries with increasing delays when your endpoint is temporarily unavailable.

Data flows one way, from InstantFeedback to your endpoint. InstantFeedback only looks at the HTTP status code your endpoint returns.

Before you start¶

• You need the admin role on the InstantFeedback account. Other members can view the webhook settings but cannot change them.
• You need an endpoint that accepts POST requests with a JSON body and answers with an HTTP 2xx status within 30 seconds. Use an https:// URL so the payload, which contains customer contact details, is encrypted in transit.
• If you want to verify signatures, your endpoint needs access to the raw request body and the account's webhook secret (see Verify the signature).

Enable the integration¶

1. Open Settings → Integrations. Each tile shows a coloured dot: green when the integration is active, red when it is not.
2. On the Generic Webhooks tile, click Settings. The first click creates the webhook configuration for your account, generates the account's webhook secret, and opens the Generic Webhooks settings page.
3. If the page title shows a red dot, click Activate in the top-right corner and confirm.

Add a webhook¶

A webhook in InstantFeedback is a named endpoint URL together with the list of events (triggers) it should receive.

1. On the Webhooks tab, click Add webhook.
2. Enter a Name that describes the destination. The name is only used inside InstantFeedback.
3. Paste the endpoint into Webhook URL.
4. Under Trigger, tick every event this endpoint should receive. Each option shows the event's label and its machine name, for example Grade received (appeal.grade). At least one trigger is required.
5. Click Save. The webhook appears in the table and a confirmation reads Webhook name added successfully.

Repeat the steps for every endpoint you want to use, for example one that receives all events and a separate one that only receives survey events.

Manage a webhook¶

Click the gear icon at the end of a row to open the webhook menu.

Click the webhook name to change its name, URL, or triggers. A confirmation reads Webhook name updated.

The test sends the following body, signed like any other delivery:

{"event": "test", "data": []}

A test succeeds when the endpoint answers with any 2xx status. It uses shorter timeouts than regular deliveries (3 seconds to connect, 10 seconds for the response) and is not retried.

Default webhook and secret¶

The Settings tab holds two account-wide settings.

Default webhook¶

The Default webhook is used by every campaign that has webhook delivery enabled and keeps Use default webhook selected. Click Edit, pick a webhook, and click Save. A confirmation reads Settings updated successfully. Leave the setting empty if every campaign should pick its own webhook.

Webhook authentication¶

Under Webhook authentication, the Secret is the key used to sign every request (see Verify the signature). One secret applies to all webhooks in the account.

• Show opens a dialog with the secret so you can read or copy it.
• Copy copies the secret to the clipboard without showing it.
• Regenerate replaces the secret with a new one and confirms with Secret regenerated successfully.

Per-campaign settings¶

Webhooks are delivered only for campaigns that have the integration switched on. Open the campaign, go to Integrations, and select the Generic Webhooks tab.

• Enabled switches webhook delivery on for this campaign. Without it, the campaign sends nothing, even if a default webhook is set.
• Webhook chooses where this campaign's events go: Use default webhook follows the account setting, or pick a specific webhook from the list.
• Include custom fields lists the campaign's custom fields. Tick the ones that should be added to every payload for this campaign. The section only appears when the campaign has custom fields.

Click Save to apply the changes. A confirmation reads Integration settings updated successfully.

Payload reference¶

Request¶

Every delivery is an HTTP POST to the webhook URL with these headers:

Redirects are not followed: a 3xx answer counts as a failed delivery. The body is a single-line JSON document in which non-ASCII characters are escaped as \uXXXX sequences; the examples below are indented for readability only.

Verify the signature¶

The signature is computed over the exact bytes of the request body, using the secret from the Settings tab as the key:

X-IFB-Signature = hex( HMAC-SHA256( key = secret, message = raw_body ) )

Compute the same value on your side and compare it with the header using a constant-time comparison. Always use the raw body as received, not a re-serialised version of the parsed JSON.

import hashlib
import hmac

def is_valid(raw_body: bytes, header: str, secret: str) -> bool:
    expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, header)

const crypto = require("crypto");

function isValid(rawBody, header, secret) {
  const expected = crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(header));
}

Envelope¶

Every body has the same shape: the event name and a list of the feedback requests the event applies to.

{
  "event": "appeal.grade",
  "data": [ { "...": "one object per feedback request" } ]
}

For appeal.send and appeal.reminder, one request is sent per campaign for every outgoing batch, so data can hold many objects. For all other events data holds exactly one object.

Events¶

Fields¶

Every object in data has these fields:

Depending on the event, these fields are added:

Each entry of survey_response has the question's id, the question text, and the value: a string for most question types, a list of strings for multiple-choice questions, or null when the question was not answered. Questions are listed in survey order.

Examples¶

A grade with two custom fields:

{
  "event": "appeal.grade",
  "data": [
    {
      "id": 481523,
      "type": "email",
      "campaign": {"id": 42, "name": "Car service"},
      "contact": "ana.novak@example.com",
      "date": "2026-09-21T08:15:30.412873+00:00",
      "grade": 9,
      "custom_fields": {"store": "Ljubljana", "order_number": "SO-10422"}
    }
  ]
}

A comment, which repeats the grade the customer gave earlier:

{
  "event": "appeal.comment",
  "data": [
    {
      "id": 481523,
      "type": "email",
      "campaign": {"id": 42, "name": "Car service"},
      "contact": "ana.novak@example.com",
      "date": "2026-09-21T08:17:02.105311+00:00",
      "grade": 9,
      "comment": "Quick turnaround and the car was washed. Thank you!",
      "custom_fields": {"store": "Ljubljana", "order_number": "SO-10422"}
    }
  ]
}

A batch of SMS requests sent for one campaign, without custom fields:

{
  "event": "appeal.send",
  "data": [
    {
      "id": 481601,
      "type": "sms",
      "campaign": {"id": 17, "name": "Store visit"},
      "contact": "+38640123456",
      "date": "2026-09-21T09:00:00+00:00"
    },
    {
      "id": 481602,
      "type": "sms",
      "campaign": {"id": 17, "name": "Store visit"},
      "contact": "+38641987654",
      "date": "2026-09-21T09:00:00+00:00"
    }
  ]
}

A completed survey:

{
  "event": "appeal.survey_complete",
  "data": [
    {
      "id": 481777,
      "type": "widget",
      "campaign": {"id": 58, "name": "Onboarding survey"},
      "contact": "session-8f3a2c",
      "date": "2026-09-21T10:42:19.884120+00:00",
      "grade": 8,
      "survey": {"id": 6, "name": "Onboarding"},
      "survey_response": [
        {"id": 31, "question": "How easy was it to get started?", "value": "4"},
        {"id": 32, "question": "Which features have you used?", "value": ["Reports", "Exports"]},
        {"id": 33, "question": "Anything we should improve?", "value": null}
      ]
    }
  ]
}

Delivery and retries¶

• Deliveries run in the background shortly after the event happens. InstantFeedback waits up to 6 seconds to connect and up to 30 seconds for your endpoint's response.
• Any 2xx status counts as delivered. The response body is ignored.
• A timeout, a connection error, or an HTTP 408, 429, or 5xx response is treated as temporary and the delivery is retried with the same body and signature. If the response carries a Retry-After header (seconds or an HTTP date), InstantFeedback waits at least that long, up to the longest interval below.
• Any other response, including 3xx redirects and other 4xx errors, is treated as permanent and the delivery is not retried.
• Retries happen after about 1 minute, 5 minutes, 15 minutes, 30 minutes, and 59 minutes (each with a few seconds of random jitter). After the fifth retry fails, the delivery is given up.
• Before every attempt, including retries, InstantFeedback checks that the integration is active and the webhook is still enabled and exists. If not, the delivery is dropped.
• Failed deliveries are not shown in the app. Keep logs on your endpoint if you need an audit trail.

Pause, reset, or remove¶

The Advanced tab shows how many campaigns have a webhook configuration and offers two account-wide actions.

• Configured campaigns shows the number of active configurations out of all saved ones. View configured campaigns lists them with a link to each campaign's settings.
• Deactivate stops all webhook deliveries. Nothing is deleted, and delivery resumes when you activate the integration again.
• Reset permanently deletes all webhooks, the default webhook setting, and all campaign configurations, deactivates the integration, and generates a new webhook secret. You have to type RESET to confirm. This cannot be undone.

Troubleshooting¶