Webhooks

Card transaction events and how to consume them.

Jeeves delivers four webhook event types covering the card-transaction lifecycle. Subscriptions, HMAC-SHA256 signatures, retries, and the circuit breaker are shared infrastructure — this page covers the card events themselves; the Webhooks integration guide covers signature verification, retries, secret rotation, and endpoint architecture in depth.

Event types

Event type	Fires when
`transaction.auth.approved`	A card authorization was approved.
`transaction.auth.declined`	A card authorization was declined.
`transaction.settled`	A card transaction settled (posted to the account).
`transaction.failed`	A card transaction failed after the authorization stage.

Typical event sequences

Scenario	Events in order
Normal purchase	`transaction.auth.approved` → `transaction.settled`
Declined purchase	`transaction.auth.declined`
Reversed / voided	`transaction.auth.approved` → `transaction.failed`
Force post (no prior auth)	`transaction.settled` only

A single purchase may emit several events over hours or days. Key your handling off the event type and relatedTransactionId — never assume a one-to-one mapping between authorizations and settlements.

The envelope

Every delivery is a POST with Content-Type: application/json:

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "type": "transaction.auth.approved",
  "version": "v1",
  "occurredAt": "2026-09-29T16:22:51Z",
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "productType": "credit_line",
    "transactionType": "debit",
    "transactionDate": "2026-09-29 16:22:51",
    "transactionAmount": 127.59,
    "transactionCurrency": "USD",
    "localAmount": 741.33,
    "localCurrency": "BRL",
    "company": { "id": "361c697b-8d82-11ec-a51a-0ea06e4de10b", "name": "Acme Corporation" },
    "user": { "id": "d5d5c940-3c58-4ecc-b772-fe20e764ed70", "name": "John Doe", "email": "john.doe@acmecorp.com" },
    "card": {
      "id": "c8ddf33f-6244-4218-af7e-7a6fe0b13528",
      "name": "Travel Card",
      "type": "virtual",
      "lastFourDigits": "9876",
      "metadata": { "reservation_code": "abc123" }
    },
    "merchant": { "name": "STARBUCKS SAO PAULO BRA", "merchantCategoryCode": "5814" }
  }
}

The id identifies the event and stays constant across delivery retries — use it for idempotency. settlementDate appears on transaction.settled; relatedTransactionId links a reversal to its original authorization. Full field tables: Payloads.

Managing subscriptions

The full subscription lifecycle is part of the public API — create, list, inspect, update (including re-activating after the circuit breaker), delete, rotate secrets with a 24-hour grace window, send test deliveries, and browse events with their delivery attempts and manual retries. The flow builder generates the complete sequence, and the Webhooks integration guide covers operational practice:

Task	Endpoint
Create subscription (returns `whsec_…` secret once)	`POST /v1/webhooks/subscriptions`
List / inspect	`GET /v1/webhooks/subscriptions`, `GET /v1/webhooks/subscriptions/{id}`
Update / re-enable	`PATCH /v1/webhooks/subscriptions/{id}`
Delete	`DELETE /v1/webhooks/subscriptions/{id}`
Rotate secret (24 h dual-signature grace)	`POST /v1/webhooks/subscriptions/{id}/rotate-secret`
Test delivery	`POST /v1/webhooks/subscriptions/{id}/test`
Browse events	`GET /v1/webhooks/events`, `GET /v1/webhooks/events/{id}`
Delivery attempts / manual retry	`GET /v1/webhooks/events/{id}/deliveries`, `POST /v1/webhooks/events/{id}/retry`

Scopes: webhooks:read / webhooks:write.

Idempotency & retries

Delivery is at-least-once. Deduplicate by the envelope id (also sent as the X-Webhook-Event-Id header), acknowledge fast with a 2xx, and do your business logic in a background worker. Repeated failures trip a circuit breaker that pauses the subscription — re-enable it with PATCH … {"status": "active"} once your endpoint recovers. Details: Retries & reliability.