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 inmetadata.specifics. Each entry is one short fact in the customer’s own terms, tagged with a theme.
specificsis empty only when the customer refused to elaborate. In that casedeclined_detailistrue.- Each fact goes through the same PII scrubbing as
summary. A fact that fails scrubbing is left out, andmetadata.pii_redactionis"failed". - Interviews prepared before this field existed have no
specificskey.
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 awebhookSecret is stored on the
workspace (see below). Requests carry the Stripe-style header:
openssl rand -hex 32 works too — any high-entropy string):
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 onoffboard.techitself; - redirects (a 3xx response counts as a failed delivery).
- Return 2xx quickly and process asynchronously
- Log all webhook payloads for debugging
- Use idempotency keys (
interview_id) to handle any duplicate deliveries - Validate the
eventfield 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: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
- Return 2xx quickly - Process asynchronously, don’t block webhook
- Verify signatures - Ensure request authenticity
- Idempotency - Handle duplicate webhooks gracefully
- Error logging - Log webhook failures for debugging
- Test in staging - Verify handler before production