Changelog

Notable changes to the Connect API, webhooks, and the @givebear/connect client. See versioning for what counts as a breaking change.

Events and registrations

• New read endpoints: GET /events (with published and upcoming filters, ticket types embedded), GET /events/{id}, and GET /events/{id}/registrations (with a status filter).
• Two new scopes: events:read and registrations:read. Registration payloads carry attendee names and emails; the check-in QR credential, Stripe ids, and tax fields are never exposed.
• Two new webhook events: registration.created (fires when a registration becomes confirmed, not at checkout start) and registration.refunded. See the event catalog.
• @givebear/connect 0.3.0 adds events.list(), events.get(), events.listAll(), events.listRegistrations(), and events.listAllRegistrations().

Embedded components, webhook rotation, and delivery logs

• POST /component-sessions mints a one-hour, read-only browser token for the new embedded components. @givebear/connect 0.2.0 adds componentSessions.create() and a @givebear/connect/components module with <givebear-donations>, <givebear-donors>, and <givebear-payouts> custom elements. See Embedded components.
• POST /webhooks/{id}/rotate-secret rotates an endpoint's signing secret with a 24-hour dual-signature grace window; verifyWebhook now accepts headers carrying multiple v1 signatures.
• GET /webhooks/{id}/deliveries lists an endpoint's recent delivery attempts. The same log appears in the dashboard, which can now also edit endpoints and rotate secrets.
• Webhook endpoint URLs must use https and resolve to a public host; registration now rejects anything else.
• Rate-limited responses (429) now include a Retry-After header.

Embedded donations

• POST /embed-sessions mints a one-hour embedded-donation session (requires the existing payments:write scope; no re-authorization needed). The session pins the fund or campaign target, preset or locked amounts, recurring default, and donor prefill server-side, and attributes donations to your app.
• @givebear/connect adds embedSessions.create().
• New @givebear/react package renders every widget as a React component, including EmbeddedDonation for sessions.
• See Embedded donations.

v1

The first version of the Connect API.

Authentication

• Org API keys (gb_live_...) and OAuth 2.0 with org-scoped access tokens (gba_...).
• Per-credential scopes, bounded by what the granting admin can do.

Read API

• donations, donors, payouts, campaigns, funds, and organization.
• Cursor pagination on every list endpoint (limit, cursor, updated_since).

Collect

• POST /payment-intents to collect a donation on an organization's behalf, settling into its own Stripe account.

Webhooks

• Endpoint management (GET/POST/PATCH/DELETE /webhooks).
• Signed, thin event payloads. Verify them with verifyWebhook from @givebear/connect.

Client

• @givebear/connect: a typed, dependency-free TypeScript client for every endpoint above.