{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-cards/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Webhooks","description":"Start today using our public API to power your next project."},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"webhooks"},"children":["Webhooks"]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Card transaction events and how to consume them."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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 ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/guides/integration-guides/webhooks/"},"children":["Webhooks integration guide"]}," covers signature verification, retries, secret rotation, and endpoint architecture in depth."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"event-types"},"children":["Event types"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Event type"},"children":["Event type"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Fires when"},"children":["Fires when"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transaction.auth.approved"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["A card authorization was approved."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transaction.auth.declined"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["A card authorization was declined."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transaction.settled"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["A card transaction settled (posted to the account)."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transaction.failed"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["A card transaction failed after the authorization stage."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"typical-event-sequences"},"children":["Typical event sequences"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Scenario"},"children":["Scenario"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Events in order"},"children":["Events in order"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Normal purchase"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transaction.auth.approved"]}," → ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transaction.settled"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Declined purchase"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transaction.auth.declined"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Reversed / voided"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transaction.auth.approved"]}," → ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transaction.failed"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Force post (no prior auth)"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transaction.settled"]}," only"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A single purchase may emit several events over hours or days. Key your handling off the event type ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["and"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["relatedTransactionId"]}," — never assume a one-to-one mapping between authorizations and settlements."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"the-envelope"},"children":["The envelope"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Every delivery is a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST"]}," with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Content-Type: application/json"]},":"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"id\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\",\n  \"type\": \"transaction.auth.approved\",\n  \"version\": \"v1\",\n  \"occurredAt\": \"2026-09-29T16:22:51Z\",\n  \"data\": {\n    \"id\": \"123e4567-e89b-12d3-a456-426614174000\",\n    \"productType\": \"credit_line\",\n    \"transactionType\": \"debit\",\n    \"transactionDate\": \"2026-09-29 16:22:51\",\n    \"transactionAmount\": 127.59,\n    \"transactionCurrency\": \"USD\",\n    \"localAmount\": 741.33,\n    \"localCurrency\": \"BRL\",\n    \"company\": { \"id\": \"361c697b-8d82-11ec-a51a-0ea06e4de10b\", \"name\": \"Acme Corporation\" },\n    \"user\": { \"id\": \"d5d5c940-3c58-4ecc-b772-fe20e764ed70\", \"name\": \"John Doe\", \"email\": \"john.doe@acmecorp.com\" },\n    \"card\": {\n      \"id\": \"c8ddf33f-6244-4218-af7e-7a6fe0b13528\",\n      \"name\": \"Travel Card\",\n      \"type\": \"virtual\",\n      \"lastFourDigits\": \"9876\",\n      \"metadata\": { \"reservation_code\": \"abc123\" }\n    },\n    \"merchant\": { \"name\": \"STARBUCKS SAO PAULO BRA\", \"merchantCategoryCode\": \"5814\" }\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}," identifies the event and stays constant across delivery retries — use it for idempotency. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["settlementDate"]}," appears on ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transaction.settled"]},"; ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["relatedTransactionId"]}," links a reversal to its original authorization. Full field tables: ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/guides/integration-guides/webhooks/payloads"},"children":["Payloads"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"managing-subscriptions"},"children":["Managing subscriptions"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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 ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/flow-builder"},"children":["flow builder"]}," generates the complete sequence, and the ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/guides/integration-guides/webhooks/"},"children":["Webhooks integration guide"]}," covers operational practice:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Task"},"children":["Task"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Endpoint"},"children":["Endpoint"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Create subscription (returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["whsec_…"]}," secret once)"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v1/webhooks/subscriptions"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["List / inspect"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v1/webhooks/subscriptions"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v1/webhooks/subscriptions/{id}"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Update / re-enable"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PATCH /v1/webhooks/subscriptions/{id}"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Delete"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DELETE /v1/webhooks/subscriptions/{id}"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Rotate secret (24 h dual-signature grace)"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v1/webhooks/subscriptions/{id}/rotate-secret"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Test delivery"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v1/webhooks/subscriptions/{id}/test"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Browse events"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v1/webhooks/events"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v1/webhooks/events/{id}"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Delivery attempts / manual retry"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v1/webhooks/events/{id}/deliveries"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v1/webhooks/events/{id}/retry"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Scopes: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["webhooks:read"]}," / ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["webhooks:write"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"idempotency--retries"},"children":["Idempotency & retries"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Delivery is at-least-once. Deduplicate by the envelope ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}," (also sent as the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["X-Webhook-Event-Id"]}," header), acknowledge fast with a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["2xx"]},", and do your business logic in a background worker. Repeated failures trip a circuit breaker that pauses the subscription — re-enable it with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PATCH … {\"status\": \"active\"}"]}," once your endpoint recovers. Details: ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/guides/integration-guides/webhooks/retries"},"children":["Retries & reliability"]},"."]}]},"headings":[{"value":"Webhooks","id":"webhooks","depth":1},{"value":"Event types","id":"event-types","depth":2},{"value":"Typical event sequences","id":"typical-event-sequences","depth":2},{"value":"The envelope","id":"the-envelope","depth":2},{"value":"Managing subscriptions","id":"managing-subscriptions","depth":2},{"value":"Idempotency & retries","id":"idempotency--retries","depth":2}],"frontmatter":{"seo":{"title":"Webhooks"}},"lastModified":"2026-10-28T18:10:31.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/cards/platform-tools/webhooks","userData":{"isAuthenticated":false,"teams":["anonymous"]}}