Event Subscription

What it is

An event subscription defines which application events should be delivered to an external URL.

It is configured on an Application and contains:

Field	Description
`url`	The webhook URL where events are sent
`secret`	The secret used to sign webhook payloads
`eventTypes`	The event type codes that trigger the subscription

Example:

{
  "url": "https://example.com/webhooks/buckaroo",
  "secret": "1234567890abcdef",
  "eventTypes": [
    "SALE.CREATE",
    "SALE.UPDATE"
  ]
}

Why it exists

An event subscription lets an application receive event notifications without polling the API.

When something relevant happens, Buckaroo sends an event notification to the configured URL. This allows integrations to react to changes in sales, transactions, or other supported resources.

How it relates to other concepts

An event subscription belongs to an Application. The Application defines the reusable integration, including its identity, scopes, OAuth credentials, and event subscription.

When the Application is installed for a merchant, the Installation can include webhook subscriptions for the event types configured on the Application. The Installation stores the installed application’s status, scopes, and creation time.

Event subscriptions are closely related to Webhooks. A Webhook is also a configuration that sends event notifications to an external URL, but the Application event subscription is defined as part of the Application itself and will make it possible to receive webhooks for all accounts in which the application is installed for.