Webhooks

Access

/webhooks is the integrators' namespace only: the hook QBitFlow's mail provider posts inbound emails to moved out of it (to an internal path, not part of this contract).

• Endpoints are the request's space's (spaces): the team's in the organization's space, a member's in their own; each mode has its own. An endpoint of another space, mode or organization answers 404.
• A member manages their endpoints only with the organization's members.webhooks policy (off by default): otherwise 403 policy_disabled (details.policy: "members.webhooks"). The team always can, acting in the member's space (switch, or an organization key with On-Behalf-Of).
• The policy applies at delivery too. While members.webhooks is off for a member, the endpoints of their space (whoever created them) receive nothing: each event is skipped, logged in the delivery log as an attempt with skipped: true and delivered: false (its error says why), never retried, and not counted against the endpoint's health. Once the policy is on again, the events published from then on are delivered; skipped ones aren't resent (resend one from the event log if needed). The organization's endpoints with includeMembers keep receiving the member's events.

Endpoints

• GET /webhooks/event-types → 200 the event types, as a bounded list: the {items, hasMore, nextCursor} envelope in one page (hasMore: false, no nextCursor).
• GET /webhooks/endpoints → 200 a page of the space's endpoints (pagination): newest first (by creation), limit 20 by default (at most 100, clamped), cursor = the previous page's nextCursor (opaque; one the API didn't give → 400 validation_failed on cursor). A space has at most 10 endpoints, so one page usually holds them all; read hasMore all the same.
• POST /webhooks/endpoints → 201 CreatedEndpoint: always payloadVersion: "v2", with its secret (whsec_…) in this response only (an API integration stores it now; the dashboard can show it again with GET …/:uuid/secret). The list and the other routes never return it.
• url is required, a valid URL (400 validation_failed on url), https in live mode on port 443 (none given), 8443 or 80 (any other port → 400 on url; test mode takes any port), and a public address: localhost, *.internal, and private, loopback, link-local, carrier-grade NAT, reserved and other non-public IPs are refused (url); the delivery also refuses them at connection time, whatever the DNS answers. These rules apply to a URL being set (POST, or a PATCH with url): an endpoint's other fields can be changed whatever its URL (an endpoint migrated from v1 may keep v1's http:// URL in live mode until its URL changes).
• events: event types from GET /webhooks/event-types, stored sorted and without duplicates; empty or absent = every type, including types added later. An unknown type, or webhook.test → 400 on events[i].
• includeMembers: the endpoint also receives the events of every member's space of the same mode (the envelope's userUuid names the member): every event of a member's space, each seller's payment.completed, subscription.created / billed / statusChanged / actionRequiredChanged / billingFailed / upcomingBill, refund.*, heldFunds.released, checkout.expired.
  • Absent, it is true for an organization endpoint (the organization's shared space): a marketplace hears of each seller's sale without asking. Send includeMembers: false to receive the organization's own events only (which include member.joined / member.removed). Endpoints created before this default keep their value; PATCH changes it.
  • Absent, it is false for a member's endpoint; true there → 400 on includeMembers (a member's space has no members).
• At most 10 endpoints per space and mode: the 11th → 409 conflict.
• Idempotency-Key (idempotency): a create retried with the same key answers the first CreatedEndpoint again (the same uuid and secret, for 24 hours) and creates no second endpoint.
• PATCH /webhooks/endpoints/:uuid changes the fields sent, the others stay (events: [] = every type, description: "" clears it: description is then absent from the endpoint). PUT is not a route (405 method_not_allowed). payloadVersion takes v2 only, the only payload version (it changes nothing today): any other value, v1 included → 400 validation_failed on payloadVersion.
• enabled: false disables the endpoint (disabledAt is set): it receives nothing, each delivery in progress stops at its next attempt (unless the endpoint is enabled again before it), and the events published while it is disabled are never sent to it. enabled: true enables it again, also after QBitFlow disabled it for failing for 3 days (live mode only, Webhook events § Failing endpoints): disabledAt is removed and the failures before don't count toward its health. Sending the state it already has changes nothing.
• How an endpoint stands (every endpoint read, and an update's answer):
  • disabledReason, while disabled: failing (QBitFlow: every delivery failed for 3 days), owner (enabled: false), closed (its member removed, its organization closed). Absent for an endpoint disabled before it was recorded, and once enabled again;
  • failingSince, while enabled and failing: its first failed attempt since its last successful one (or since it was enabled again). After a day its team is emailed and the dashboard raises it; after 3 it is disabled (Webhook events § Failing endpoints; a test-mode endpoint is never emailed about nor disabled for failing). Absent while it delivers;
  • lastDeliveredAt: when it last received an event. Absent if it never did.
• DELETE /webhooks/endpoints/:uuid → 204 (no body): the endpoint receives nothing more, pending retries included. Its delivery history is deleted with it: the event log no longer lists its deliveries (GET /webhooks/events/:id), and GET …/:uuid/deliveries answers 404. Disable it instead (PATCH { "enabled": false }) to keep that history. Deleted, it answers 404 (a second DELETE too).
• POST …/:uuid/rotate → 200 EndpointSecret, from the dashboard only (like GET …/secret; an API key → 404 and nothing changes: a leaked key must not be able to read a new secret and sign deliveries the integration would accept). The new secret signs every delivery from now on (retries included), and for 24 hours the previous secret signs them too (a second v1= in QBitFlow-Signature, after the new one), so the receiver can switch secrets without losing deliveries. rotatedAt records when.

Endpoints migrated from v1

• v1's webhook URLs became endpoints of their space and mode (v1's transaction URL receives payment.completed and subscription.created, v1's recurring URL subscription.billed and subscription.statusChanged). The v2 launch (v1 retired, 2026-10-24) moved them all to the envelope (payloadVersion: "v2") with the secret they signed with: v1's secret of their space (one shared by both modes' endpoints; an owner v1 gave none got a new one). From then on they are endpoints like any other: their own secret, rotated with the 24-hour overlap, any event type.

Test event

• POST …/:uuid/test → 200 TestResult: posts one event, signed like any delivery, once (no retry), and answers how the endpoint answered: delivered (a 2xx), statusCode, and error when it wasn't delivered (the endpoint's status and the start of its answer, or why it got no answer: a fixed reason such as "the endpoint refused the connection", never the address QBitFlow dialed). A failed test is still 200. A disabled endpoint can be tested (to check it before enabling it again); a test never counts toward its health. A member's endpoint whose events are skipped (members.webhooks off for that member) → 403 policy_disabled: a test must not succeed where the real events don't go out.
• At most 30 tests an hour per space (LimitPerSpace(webhookTests)), every endpoint and credential together → 429 rate_limit_exceeded, nothing sent (each test may hold the request up to 30 seconds).
• The endpoint receives a webhook.test event (data: {endpointUuid, message}).

Event log

The space's events as they were delivered, and how each delivery went (Stripe's event list and delivery log). Events are kept at least 90 days.

• GET /webhooks/events → 200 a page of the request's space's events, newest first (the events of one publication latest first), each its envelope exactly as delivered (Webhook events § The envelope). Cursor pagination (pagination): limit (default 20, at most 100), cursor = the previous page's nextCursor, opaque. The log pages on each event's creation time, its position in its publication and its id, so the events of one publication (created together) are each listed once across pages, in order. A cursor the API didn't give → 400 validation_failed on cursor (never an empty page).
  • :id is an event's id (evt_…, at most 64 characters: 400 on id otherwise).
  • type keeps one event type (GET /webhooks/event-types); an unknown type → 400 on type.
  • includeMembers=true, for the organization's space only, adds its members' events of the same mode (userUuid names the member); from a member's space → 400 on includeMembers.
  • A member sees their own space's events: member.joined / member.removed are the organization's. Nothing of another organization or mode, ever.
• GET /webhooks/events/:id → 200 EventDetail: the envelope and deliveries, one per endpoint of the request's space the event went to or is queued for (an endpoint of another space isn't listed: the organization doesn't see a member's endpoints there, nor a member the organization's), with delivered (one attempt answered 2xx) and every attempts[] entry oldest first (attempt, delivered, statusCode when the endpoint answered, error, durationMs, attemptedAt). The organization's space reads its members' events too; any other event → 404.
• Where a member's deliveries show: a member's event goes to their own endpoints and to the organization's endpoints with includeMembers. Read its deliveries to the organization's endpoints from the organization's space (list it with includeMembers=true, then GET /webhooks/events/:id); read as the member (On-Behalf-Of), the same event lists only the member's own endpoints: deliveries: [] when they have none, although the organization's endpoint got it.
• Whether a delivery goes on: pending (always present). true while QBitFlow still attempts the event on its own; then exactly one of these describes it:

| The delivery | attempts | delivered | pending | nextAttemptAt | waitingFor | |---|---|---|---|---|---| | Delivered | ≥ 1 | true | false | absent | absent | | Retried after a failed attempt | ≥ 1 | false | true | the next attempt | absent | | Queued behind an earlier event of its publication (§ Delivery and retries in Webhook events: an endpoint gets a publication's events in order) | [] | false | true | absent | that event's evt_… | | Not started yet (QBitFlow starts it within a minute) | [] | false | true | absent | absent | | Abandoned after its retries (3 days live, 3 hours in test mode) | ≥ 1 | false | false | absent | absent | | The endpoint was disabled meanwhile | as they were | false | false | absent | absent |

A deleted endpoint's deliveries are deleted with it: the event no longer lists them (its successful ones included), as if it never had that endpoint. To keep an endpoint's history, disable it (PATCH …/:uuid { "enabled": false }) rather than delete it.

So an entry can have attempts: []: a queued event is listed as soon as it is queued, never shown as unsent. An event a queued one waits for is in the same publication (the same createdAt): subscription.billed waits for its subscription.created, never for an earlier publication. If QBitFlow can't read a delivery's progress at that moment, the event still answers 200, and pending comes from the attempts: true while the retry schedule still attempts the event again (so a delivery being retried never reads as abandoned), without nextAttemptAt; a delivery queued with no attempt yet isn't listed until its progress can be read: read it again a moment later.

• GET /webhooks/endpoints/:uuid/deliveries → 200 a page of the attempts to one endpoint of the request's space, newest first by when they were attempted (default 20, at most 100; cursor = the previous page's opaque nextCursor), each with its eventId and eventType. delivered=false keeps the failed attempts (what to look at when the endpoint is reported failing), delivered=true the delivered ones. Another space's endpoint → 404.
• POST /webhooks/events/:id/resend {endpointUuid} → 200 TestResult: posts the event to that endpoint once, now, signed like any delivery (the same event id, a new t), and answers how the endpoint answered (a failed attempt is still 200). It is sent even if the event was already delivered. It is logged as the next attempt (resends and automatic retries share one sequence per event and endpoint) and counts for the endpoint's health (a success ends a failing streak). A delivery still in progress goes on while the event fails; once a resend delivered it, the delivery's next retry sends nothing and the retries stop (nothing more is logged). The endpoint must be one of the request's space's that receives the event (its types, its payload version, includeMembers for a member's event): otherwise 409 conflict; a disabled endpoint → 409 conflict (enable it first). An event or endpoint the request's space doesn't see → 404; endpointUuid missing → 400.
• A resend to a member's endpoint while the organization's members.webhooks policy is off for them (the team resending in the member's space; the member themselves gets 403 policy_disabled) posts nothing: 200 TestResult with delivered: false, no statusCode, and error saying the policy is off. It is logged as a skipped attempt (skipped: true), and doesn't count for the endpoint's health.
• At most 100 resends an hour per space (LimitPerSpace(webhookResends)) → 429 rate_limit_exceeded, nothing sent. A resend refused for another reason (404, 409) still counts.

Verify

• POST /webhooks/verify checks a delivery an endpoint of the request's space received: endpointUuid, the raw body exactly as received, and the QBitFlow-Signature header as signature. All three required (400 validation_failed).
• Valid → 200. A body, signature or secret that doesn't match, a malformed header, or a timestamp more than 5 minutes from the server clock (either way: replays) → 400 invalid_signature. Another space's endpoint → 404.
• The SDKs verify locally with the same rule (no call needed): see Webhook events.