Webhooks

If your organization has webhooks configured, you’ll receive HTTP POST notifications when case state changes.

Delivery & Security

• Requests are JSON (Content-Type: application/json). A 2xx response marks the delivery successful.
• Authentication — configurable per subscription: HMAC signature (hmac_sha256), bearer token, basic auth, or OAuth2 client credentials. With hmac_sha256, every request carries X-Webhook-Signature: sha256=<hex> — the HMAC-SHA256 of the raw request body, keyed with your shared secret; verify it before trusting the payload. The other methods send the corresponding Authorization header.
• Retries — failed deliveries are retried up to 10 times with exponential backoff (capped at 1 hour). Retryable: connection errors, timeouts, HTTP 5xx, 408, and 429. Any other 4xx is permanent and not retried. Requests time out after 10 seconds; redirects are not followed.

Common payload envelope

Every event carries event (the event name), timestamp (ISO 8601), and a case object with id, status (the event-name suffix), case_type (policy_limit_search | policy_existence_search | unknown), and issue_key. Exceptions: issue_key is absent on case.received (not yet assigned at submission) and may also be absent on a case.files_updated fired before the case is assigned its issue key; case.additional_policies_found uses a reduced case object (below).

Events

• case.received — Case queued for processing.
• case.files_updated — A file was added to the case after submission. The case object includes file: {"file_id": "<uuid>", "label": "<category label>"}. Fires when the file is stored on our side; it may not yet be visible to researchers at that instant.
• case.in_progress — Research has begun.
• case.action_required — Additional information or documents needed. Payload includes interaction_id and message (the triggering comment body, capped at 8 KB UTF-8 — truncated content ends with …). Respond via POST /api/v1/partner/cases/{case_ref}/respond/ with the interaction_id.
• case.additional_policies_found — Researchers located additional policies available for purchase. Payload has a reduced case object (id + issue_key only) plus top-level offer_id and additional_policies — one entry per offered policy with upgrade_id, type, researcher_note, price_usd, and status (created = newly offered, selected = already accepted). Policy values (carrier, limits) are never included pre-acceptance. Accept via POST /api/v1/partner/cases/{case_ref}/offers/accept/.
• case.results_ready — Results available. Payload includes a presigned download URL (results_url, valid ~12 hours from delivery) and the object filename (file_name). Re-fires when results are regenerated (e.g., after an additional-policy acceptance).
• case.closed — Case has been closed. Payload includes a top-level reason field: results_delivered means the search was completed and the results were delivered (e.g. on full payment, or a close where results were already delivered). For any other close, reason is a human-readable closing note written by our staff — free text (truncated to 32,768 characters, ending with … if cut), falling back to the literal cancelled when no note is available. Do not parse reason as an enum. Note: the case.closed webhook (with reason: results_delivered) is the authoritative close signal and may precede the read API reporting closed. GET /api/v1/partner/cases/{ref}/ only reports closed once the case reaches its terminal internal state; during an intermediate post-payment stage it still reports results_ready. Treat the webhook as authoritative — do not expect the read API to immediately reflect closed after receiving this event.

Contact Red Folder Research to configure webhook subscriptions.