Webhooks

Webhooks let you receive Setgreet events at any HTTP endpoint you control. This is the most flexible integration -- use it to pipe events into your own backend, a data warehouse, a Slack channel via Zapier, or any other system that accepts HTTP requests.

How webhooks work

When an event occurs in Setgreet (a flow is displayed, a user completes a flow, a component is interacted with), Setgreet sends an HTTP POST request to your webhook URL with the event payload.

Setup

Click Integrations in the sidebar.
Click Add Integration and select Webhook.
Enter your Webhook URL -- the endpoint that will receive events.
Optionally set a Secret to sign payloads with HMAC-SHA256.
Select which event types to forward (see event types).
Click Save.

Payload format

Every webhook request is an HTTP POST with a JSON body that batches one or more events inside a delivery envelope:

{
  "events": [
    {
      "event": "flow_completed",
      "timestamp": "2026-06-15T14:32:10.123Z",
      "userId": "user_abc123",
      "properties": {
        "flowId": "flow_xyz789",
        "flowName": "Onboarding Walkthrough",
        "screenId": "screen_456",
        "screenName": "Welcome",
        "componentId": "comp_789",
        "componentType": "button",
        "componentLabel": "Get Started",
        "sessionId": "session_abc",
        "appId": "app_def",
        "organizationId": "org_ghi",
        "custom": {}
      },
      "context": {
        "source": "setgreet",
        "platform": "ios"
      }
    }
  ],
  "deliveredAt": "2026-06-15T14:32:10.500Z",
  "source": "setgreet"
}

Envelope fields

Field	Description
`events`	An array of one or more event objects delivered in this request.
`deliveredAt`	ISO 8601 timestamp of when Setgreet sent this delivery.
`source`	Always `"setgreet"`.

Event object fields (inside `events[]`)

Field	Description
`event`	The event type string (see event types).
`timestamp`	ISO 8601 timestamp of when the event occurred.
`userId`	The end user's ID (as set via the SDK `identifyUser` call).
`properties.flowId`	The ID of the flow involved.
`properties.flowName`	The human-readable name of the flow.
`properties.screenId`	The screen ID (present for screen-level and component-level events).
`properties.screenName`	The screen's display name.
`properties.componentId`	The component ID (for component events).
`properties.componentType`	The component's type (e.g., `button`, `rating`, `textInput`).
`properties.componentLabel`	A human-readable label for the component.
`properties.sessionId`	The SDK session identifier.
`properties.appId`	The app the event originated from.
`properties.organizationId`	The organization the app belongs to.
`properties.custom`	Additional event-specific data (component values, ratings, etc.).
`context.source`	Always `"setgreet"`.
`context.platform`	The platform the event came from (e.g., `ios`, `android`).

For high-volume apps, multiple events may be batched into a single delivery. Always iterate over the events array instead of assuming a single event per request.

Signing and verification

If you set a webhook secret, Setgreet signs every payload with an HMAC-SHA256 signature computed from the raw JSON request body and your secret. The signature is sent in the X-Setgreet-Signature HTTP header as a lowercase hex-encoded digest.

Verify the signature on your server by computing the HMAC-SHA256 of the raw request body with the same secret and comparing it to the header. This confirms the request really came from Setgreet and the body was not modified in transit.

Retry behavior

If your endpoint returns a non-2xx status code or times out, Setgreet retries delivery automatically:

Each request has a 10-second timeout. If your endpoint does not respond within that window, it counts as a failure.
Failed deliveries are retried up to 3 times with fixed delays of 1 second, 10 seconds, and 60 seconds between attempts.
A Retry-After response header is honored when present, overriding the default delay for that attempt.
After all retries are exhausted, the event is moved to the dead-letter queue and no longer retried.

Monitoring delivery status

On the integration detail page you can check delivery health:

Recent deliveries -- a list of recent webhook calls with their HTTP status codes and timestamps.
Delivery chart -- a visualization of delivery volume and failure rate over time.
Dead-lettered events -- events that exhausted all retries, available for inspection.

If an integration repeatedly fails, Setgreet may automatically pause it to avoid wasted requests. You can unpause it once the endpoint is healthy again.

Best practices

Respond quickly. Your endpoint should return a 200 status code as fast as possible. Process the event asynchronously if needed -- acknowledge receipt first, then handle the data.
Validate the payload. Check the event field and structure before processing. Ignore unknown event types gracefully to avoid breaking when new events are added.
Verify the HMAC signature if you configured a secret, especially for webhooks exposed to the public internet.
Use a queue. For high-volume apps, have your webhook endpoint push events into a message queue (SQS, RabbitMQ, etc.) and process them with a worker.

Webhooks

On this page