Payloads
Every webhook delivery is an HTTP POST with Content-Type: application/json. The body wraps the transaction inside an event envelope.
Envelope fields
| Field | Type | Description |
|---|---|---|
id | string (UUID) | Unique event ID. Use this for idempotency. |
type | string | Event type, e.g. transaction.auth.approved |
version | string | Payload schema version, e.g. v1 |
occurredAt | string (ISO-8601 UTC) | When the event occurred |
data | object | Transaction data object (see below) |
Transaction data object
| Field | Type | Description | |
|---|---|---|---|
id | string (UUID) | required | Unique transaction identifier |
productType | string | required | credit_line or self_funded |
transactionType | string | required | debit or credit |
transactionDate | string (ISO-8601) | required | Date and time of the transaction |
transactionAmount | number | required | Amount in the billing currency |
transactionCurrency | string | required | ISO-4217 code (e.g. USD, BRL) |
settlementDate | string | optional | Settlement date. Present on transaction.settled. |
localAmount | number | optional | Amount in the merchant's local currency |
localCurrency | string | optional | ISO-4217 code of the local currency |
description | string | optional | Human-readable transaction description |
relatedTransactionId | string (UUID) | optional | ID of the related transaction (e.g. original auth for a reversal) |
company | object | required | { id, name } |
user | object | required | { id, name, email } |
card | object | required | See Card object below |
merchant | object | required | See Merchant object below |
Card object
| Field | Type | Description | |
|---|---|---|---|
id | string (UUID) | required | Card identifier |
name | string | optional | Card display name |
type | string | required | virtual or physical |
lastFourDigits | string | required | Last 4 digits of the PAN |
metadata | object | optional | Custom key-value metadata on the card |
restrictions | object | optional | { spendLimit, activeDateRangeUTC, maxTransactionCount, merchantCategory } |
Merchant object
| Field | Type | Description | |
|---|---|---|---|
name | string | required | Merchant name |
merchantCategoryCode | string | required | 4-digit ISO 18245 MCC (zero-padded) |
merchantCategoryCodeDescription | string | optional | Human-readable MCC description |
Full example payload
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"type": "transaction.auth.approved",
"version": "v1",
"occurredAt": "2026-04-20T10:00:00.000Z",
"data": {
"id": "txn-uuid-1234-5678-abcd",
"productType": "credit_line",
"transactionType": "debit",
"transactionDate": "2026-04-20T10:00:00.000Z",
"transactionAmount": 150.00,
"transactionCurrency": "USD",
"localAmount": 820.50,
"localCurrency": "BRL",
"description": "Hotel booking - Marriott Sao Paulo",
"company": { "id": "co-uuid-5678", "name": "Acme Corp" },
"user": { "id": "u-uuid-9012", "name": "John Doe", "email": "john@acme.com" },
"card": {
"id": "card-uuid-3456",
"name": "Travel Card",
"type": "virtual",
"lastFourDigits": "1234",
"metadata": { "itineraryId": "ITIN-993235" },
"restrictions": { "spendLimit": 500.00, "maxTransactionCount": 3 }
},
"merchant": {
"name": "Marriott Hotels",
"merchantCategoryCode": "3509",
"merchantCategoryCodeDescription": "Marriott Hotels"
}
}
}Delivery headers
Every webhook request from Jeeves carries these HTTP headers:
| Header | Example | Description |
|---|---|---|
X-Webhook-Event-Id | a1b2c3d4-… | Unique event ID — use as your idempotency key |
X-Webhook-Delivery-Id | d9e8f7a6-… | Unique delivery attempt ID |
X-Webhook-Event-Type | transaction.auth.approved | The event type |
X-Webhook-Timestamp | 1745143200 | When the event occurred (Unix seconds) |
X-Webhook-Signature | sha256=abc123… | HMAC-SHA256 of the raw request body |
X-Webhook-Retry | false | true if this is a retry attempt |
X-Webhook-Retry-Reason | automatic | automatic or manual — only on retries |
X-Webhook-Test | true | Present only on test deliveries |
Content-Type | application/json | Always application/json |