API docs by Redocly

BudgetBakers Partner Webhooks (2.0.0-draft.2)

Download OpenAPI specification:

E-mail: integration@budgetbakers.com License: Proprietary

Connection lifecycle callbacks that BudgetBakers POSTs to the partner's configured callback URL. The URL is configured in the partner portal — it is not passed per request.

Highlights

  • eventId — stable UUID per event, identical across retries. Deduplicate on it.
  • X-BB-Signature — HMAC-SHA256 signature header (see Security below).
  • reason — structured {code, message} on *Failed and Consent* events.
  • Default retry policy for portal-onboarded partners: terminal events retried at 1h, 3h, 7h, 12h, 24h after the initial attempt. Progress events are delivered once, without retry.

Handling rules

  • Respond with any 2xx to acknowledge. Non-2xx and timeouts count as delivery failures and are retried per the partner's retry policy.
  • Respond 2xx and ignore unknown event types. New types may be added at any time; rejecting them only floods your endpoint with retries.
  • The webhook stream is the authoritative completion signal; browser redirects (resultCode) are a UX convenience only.
  • Events may arrive out of order across types; order within retries of a single event is meaningless. Use eventId for dedup and createdAt plus your own state machine for ordering decisions.

Security

Every delivery carries the HMAC signature header X-BB-Signature: t=<unix-ts>,v1=<hex> where hex = HMAC_SHA256(secret, "{t}." + raw_request_body). Verify with a constant-time comparison against every currently active secret (two are active during rotation) and reject when |now - t| > 300 seconds (replay protection). Secrets are generated and rotated in the portal. Server SDKs ship a webhooks.verify() helper.

Connection lifecycle event Webhook

Sent for every lifecycle event of the partner's connections. See the type enum for the live event set. Which terminal event closes an operation depends on the operation: create ends in ConnectionCreateSuccess / ConnectionCreateFailed, a reconnect and a provider migration in ConnectionReconnectSuccess / ConnectionReconnectFailed, and every refresh (manual and automatic) in ConnectionRefreshSuccess / ConnectionRefreshFailed. TransactionsFetching* progress events are reused during refresh; AccountsFetching* occur only on create and reconnect.

Authorizations:
SignatureV2
Request Body schema: application/json
required
eventId
required
string <uuid>

Stable per event, identical across retries. Deduplication key.

type
required
string (WebhookEventType)
Enum: "AuthenticationStarted" "AuthenticationSuccess" "AuthenticationFailed" "AuthenticationCanceled" "AccountsFetchingStarted" "AccountsFetchingSuccess" "AccountsFetchingFailed" "TransactionsFetchingStarted" "TransactionsFetchingSuccess" "TransactionsFetchingFailed" "ConnectionCreateSuccess" "ConnectionCreateFailed" "ConnectionReconnectSuccess" "ConnectionReconnectFailed" "ConnectionRefreshSuccess" "ConnectionRefreshFailed" "ConnectionDeleted" "ConnectionConsentRevoked" "ConnectionConsentExpired"

Live event set. Progress events (Authentication*, AccountsFetching*, TransactionsFetching*) are delivered once without retry by default; terminal events are retried. Handle unknown values by acknowledging and ignoring.

clientId
required
string <uuid>
connectionId
required
string <uuid>
createdAt
required
string <date-time>

When the event was produced by BudgetBakers.

object (WebhookReason)

Present on *Failed and Consent* events.

property name*
additional property
any

Responses

Request samples

Content type
application/json
Example
{
  • "eventId": "7d2c4f7e-1a9b-4c3d-8e5f-6a7b8c9d0e1f",
  • "type": "ConnectionCreateSuccess",
  • "clientId": "538efad5-0966-4ca4-86e2-0856d115cbb6",
  • "connectionId": "38d0322a-a01f-4ab5-811a-7014b597834a",
  • "createdAt": "2026-07-15T08:10:30.000Z"
}