How to secure Bubble backend workflows used as partner APIs

The short answer

Use Bubble's built-in bearer authentication when the caller can authenticate as a Bubble user or administrator. For third-party webhooks that cannot use Bubble bearer tokens, receive the request through a small verification service that validates the provider's signature over the raw body, enforces a timestamp window, deduplicates the delivery ID, and then calls a non-public or authenticated Bubble workflow with a narrow internal credential.

Do not build a public workflow that compares a reusable API key from the request body and then assumes every later action is authorized. Authentication identifies the caller; the workflow still needs to authorize the specific tenant, operation, and target record.

The forum question behind this article asked how to read an API key from request headers for a public backend workflow. Bubble can include headers in automatically detected webhook data, but detection alone does not provide rotation, replay defense, constant-time signature validation, or provider-specific verification. See Backend Workflow API Authentication.

Choose the authentication path

Bubble documents three Workflow API access levels: no authentication, authenticated users and admins, or admins only. Its authentication guide uses Authorization: Bearer <token> for incoming API requests.

Use the paths deliberately:

• First-party client acting as a Bubble user: Bubble user bearer token plus privacy rules and workflow conditions.

• Trusted internal automation: narrowly held server credential, never exposed to a page.

• External webhook provider: provider signature verification at a dedicated boundary, then an authenticated internal call.

• Partner API client: individual client identity, revocable credential, scoped operations, and tenant binding; avoid one shared secret for every partner.

Do not put credentials in query strings. URLs are more likely than headers to be stored in logs and histories. Bubble's API Connector security guide likewise recommends marking sensitive outgoing parameters private so they remain server-side.

Verify signed webhooks over the raw body

Many webhook providers compute an HMAC signature from the exact request bytes. The receiver recomputes it with the shared secret and compares the values in constant time. GitHub's webhook validation guide documents this model and warns against ordinary string equality.

The locally tested reference uses:

const signed = `${timestamp}.${rawBody}`
const expected = `sha256=${createHmac("sha256", secret).update(signed).digest("hex")}`

if (Math.abs(nowSeconds - timestamp) > 300) reject("expired")
if (!timingSafeEqual(Buffer.from(expected), Buffer.from(received)))
  reject("invalid")

const signed = `${timestamp}.${rawBody}`
const expected = `sha256=${createHmac("sha256", secret).update(signed).digest("hex")}`

if (Math.abs(nowSeconds - timestamp) > 300) reject("expired")
if (!timingSafeEqual(Buffer.from(expected), Buffer.from(received)))
  reject("invalid")

const signed = `${timestamp}.${rawBody}`
const expected = `sha256=${createHmac("sha256", secret).update(signed).digest("hex")}`

if (Math.abs(nowSeconds - timestamp) > 300) reject("expired")
if (!timingSafeEqual(Buffer.from(expected), Buffer.from(received)))
  reject("invalid")

The test proves that an authentic current body succeeds, a one-character body change fails, and the same valid signature fails after the replay window. The implementation is available in forum-operations-reference.mjs.

Provider formats differ. Use the provider's required header names, canonical string, multiple-secret rotation behavior, and tolerance rules. Parse JSON only after signature verification; reserializing JSON can change whitespace or key order and invalidate a correct signature.

Use /initialize only to detect the schema

Bubble's Workflow API documentation explains that /initialize puts an endpoint into data-detection mode. It is not the production webhook URL. Detect the sample in the development version, review and save the parameter types, deploy the workflow, and configure the provider with the normal endpoint without /initialize.

If a signature header is needed, select Include headers in the detected data during detection. This makes the value available to the workflow, but a complex HMAC algorithm may be safer and easier to test in a purpose-built verification service than in visual workflow expressions.

Authorize the action after authentication

After caller verification, map the external account or client ID to one internal tenant. The request may name a resource, but the server must confirm that resource belongs to the mapped tenant and that the client may perform the operation.

Apply an allowlist:

• allowed client;

• allowed operation;

• allowed tenant;

• allowed resource type;

• bounded payload size;

• required event type and schema version.

Bubble's Workflow API privacy rules guide notes that privacy rules constrain database access but do not prevent the workflow itself from running. Add workflow-level conditions and explicit target checks rather than assuming privacy rules are the complete authorization boundary.

Acknowledge quickly and process once

Webhook providers often retry when they do not receive a prompt successful response. A robust verifier should:

1. validate transport and signature;

2. reject stale timestamps;

3. store the provider delivery ID with a unique constraint or transactional claim;

4. enqueue bounded work;

5. return a 2xx acknowledgment;

6. process asynchronously;

7. record the final result separately.

GitHub recommends returning a 2xx response within ten seconds in its webhook best practices. Other providers have different deadlines. Do not make the provider wait for a long Bubble workflow if a queue or job record can acknowledge receipt first.

Credential rotation

Support two active verification secrets during rotation: current and previous. Try the current secret first, then the previous secret for a short overlap period. Record which secret version matched without recording the secret. Remove the previous version after all configured senders use the new one.

For partner bearer credentials, store hashes when the raw token need not be recovered. Show the value once, bind it to one client and scope, and support immediate revocation. Never place the complete token in Bubble logs or a database field readable by ordinary users.

Negative tests

• Missing authentication is rejected before business actions.

• A valid signature over a modified body is rejected.

• A valid old signature is rejected outside the tolerance window.

• Replaying the same delivery ID returns an idempotent acknowledgment.

• Tenant A's credential cannot mutate tenant B's record.

• A valid client cannot call an unapproved operation.

• An oversized payload is rejected before persistence.

• Rotated previous credentials work only during the overlap window.

• Error responses contain a request ID, not secrets or raw payloads.

The HMAC and replay-window logic passed automated tests on 2026-10-02. Before publishing a provider-specific tutorial, reproduce the complete handshake against that provider's documented test webhook.

Primary CTA: Describe the partner or webhook system that needs to trigger your Bubble app.

Sources checked: Bubble Workflow API, API authentication, Workflow API privacy rules, GitHub validating webhook deliveries, and webhook best practices, checked 2026-10-02.