Skip to main content
Offboard.tech sends webhook notifications when interviews are completed, saved, or abandoned. Configure your webhook URL in workspace settings to receive real-time updates.

Configuration

Set your webhook URL in workspace settings:

Events

interview.completed

Customer completed the interview without accepting a save offer:

interview.saved

Customer accepted a save offer:

interview.abandoned

Customer left mid-interview (sent via weekly reports, not real-time):

Payload Schema

Interview Specifics

Before it completes, the agent asks one concrete follow-up for each complaint: which page, price, or plan element; which onboarding step; how long it took; what the customer expected instead. It records the answers in metadata.specifics. Each entry is one short fact in the customer’s own terms, tagged with a theme.
  • specifics is empty only when the customer refused to elaborate. In that case declined_detail is true.
  • Each fact goes through the same PII scrubbing as summary. A fact that fails scrubbing is left out, and metadata.pii_redaction is "failed".
  • Interviews prepared before this field existed have no specifics key.

Trust flags

Offboard also stores request provenance in metadata: country, asn, ua_class (browser / bot / script), and ip_hash (a keyed hash, never the raw IP). Your link params can never overwrite these keys.

Sentiment Values

Handling Webhooks

Basic Handler

Verifying Signatures

Every outbound webhook is signed when a webhookSecret is stored on the workspace (see below). Requests carry the Stripe-style header:
Verify it before trusting the payload:
Store the secret (write-only, AES-256-GCM at rest — never returned by any endpoint). Easiest path: Dashboard → Settings → Webhook Configuration → “Generate signing secret” — shown once, rotate anytime. Or via API (openssl rand -hex 32 works too — any high-entropy string):
Webhooks sent before a webhookSecret is stored are unsigned. SSRF protection: Offboard only sends webhooks (and Zapier hook deliveries) to public https:// URLs. It rejects:
  • private, loopback, link-local, and cloud-metadata addresses (localhost, 10.x, 172.16–31.x, 192.168.x, 127.x, 169.254.x, IPv6 ULA/link-local), in any notation;
  • hostnames whose DNS records point at any of those addresses (checked before every delivery, so a hostname that later re-points to a private address stops receiving);
  • URLs with credentials (https://user@host/) and URLs on offboard.tech itself;
  • redirects (a 3xx response counts as a failed delivery).
Webhook URLs pointing to internal infrastructure are rejected when you save them or silently skipped at delivery. Recommended practices for your webhook handler:
  1. Return 2xx quickly and process asynchronously
  2. Log all webhook payloads for debugging
  3. Use idempotency keys (interview_id) to handle any duplicate deliveries
  4. Validate the event field before processing

Delivery & Retries

Webhooks are delivered through a durable outbox. When an interview is finalized, the status change and the webhook event are committed in the same database transaction — a crash between the two cannot lose the event. Handle duplicates: retries and the scheduled sweep can produce a second delivery after a crash. Key your handler on metadata.event_id (or interview_id + event) and return 2xx for repeats.

Testing

Test Webhook Endpoint

Use the test endpoint to verify your webhook handler:
Test sends are signed with your stored webhookSecret (if configured), so this also verifies your signature-checking code end to end. If your handler returns 401, confirm it verifies x-offboard-signature with the current secret — rotate it via Settings → Webhooks if unsure. Test sends are limited to 5 per minute per account; more return 429 with Retry-After: 60.

Local Testing

Use ngrok or similar to test webhooks locally:

Sample Payloads

Rate Limiting

Webhooks are sent per interview completion. Bulk events (weekly reports) are sent as single webhook with batched data.

Best Practices

  1. Return 2xx quickly - Process asynchronously, don’t block webhook
  2. Verify signatures - Ensure request authenticity
  3. Idempotency - Handle duplicate webhooks gracefully
  4. Error logging - Log webhook failures for debugging
  5. Test in staging - Verify handler before production