Webhook Concepts

Webhook Event Format

Webhooks are sent using the Cloud Events format with the HTTP protocol binding. The Cloud Event data is specified by a JSON schema for each webhook listed on each webhook's reference page. All webhook JSON schemas have the common Identity object, which will always contain at least a tenantID. These identity fields are useful for determining the related entities to this webhook, e.g. which merchant.

Example Webhook HTTP Request

POST / HTTP/1.1
Host: 127.0.0.1:59281
Accept-Encoding: gzip
Authorization: Basic dGVzdC11c2VyOnNlY3JldC1wYXNzd29yZA==
Ce-Id: 0c6b703f-d9f2-444c-ba3d-ac67eb81f43b
Ce-Source: breadpayments.webhooks.webhook
Ce-Specversion: 1.0
Ce-Time: 2023-04-27T17:41:51.756578Z
Ce-Type: integration_test_event
Content-Length: 113
Content-Type: application/json
Date: Thu, 27 Apr 2023 17:41:51 GMT
Timestamp: 2023-04-27T17:41:51.799047Z
User-Agent: BreadPay-Webhooks/2.0
X-Jws-Signature: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpPU0UiLCJraWQiOiJiZDlmOWEwZi1hNWRiLTQyNDctOTdmYS0xYWQ2N2I1OThhOWMiLCJjcml0IjpbIlRpbWVzdGFtcCJdLCJUaW1lc3RhbXAiOiIyMDIzLTA0LTI3VDE3OjQxOjUxLjc5OTA0N1oifQ..4bu1E0FKjceYNyTewXV15tdKtW66rPv3K_eggdLW0Rc

{"identity":{"tenantID":"f8605cc2-32c8-4ec0-bab7-ad008f00b6fa"},"someIntField":1,"someStringField":"e2e event 1"}

The Cloud Event headers are set as follows:

Cloud Event Header	Details
`ce-id`	A unique UUID representing the event that triggered this webhook
`ce-source`	The name of the domain that generated the webhook
`ce-type`	The webhook's event type
`ce-time`	The time of event being created.
`timestamp`	The time of sending (to your HTTP endpoint, not the original time of the event)

📘
Use the ce-source in combination with the ce-type to distinguish between different types of events

Event Listing

The lists of available webhooks can be found in the API Reference section by expanding "Webhooks" under each domain. Each webhook is specified by a JSON schema made available on its page. Subscriptions can be made to any number of webhooks, specifying either exact webhooks or using a wildcard to subscribe to all webhooks within a namespace.