Webhooks

When a report completes (sync or async), Swippee POSTs the result to every active webhook endpoint on your organization.

Signature

Each delivery is signed so you can verify it came from Swippee:

X-Swippee-Signature: t=<unix>,v1=<hex>

v1 is an HMAC-SHA256 of <t>.<raw body> using your webhook signing secret. Reject deliveries where the timestamp is too old or the signature doesn’t match.

Payload

Every delivery shares one envelope. The event is split into a grouping (event_type) and a specific code (event_code); event is the canonical dotted name. Switch on event_code.

{
  "event": "report.ready",
  "event_type": "REPORT",
  "event_code": "READY",
  "report_id": "rep_abc123",
  "environment": "live",
  "created_at": "2026-05-27T10:23:41Z",
  "result": { }
}

`event`	When
`report.ready`	A report finished parsing. `result` is the full `StatementReport`.
`report.failed`	A report could not be produced. `error` is `{ error_code, error_message }`.

Webhooks are hints — always reconcile against GET /v1/reports/{id} as the source of truth, since deliveries can arrive out of order or be retried.

Retries

Failed deliveries retry with exponential backoff for up to 24 hours. Return a 2xx quickly and process asynchronously to avoid timeouts.

Get started

Core concepts

Guides

Signature

Payload

Retries

​Signature

​Payload

​Retries

Signature

Payload

Retries