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. ConnectionRefreshSuccess / ConnectionRefreshFailed fire for every refresh operation (manual and automatic). 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" "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"
}