Skip to main content

Bridge webhooks

Updated

Bridge supports two kinds of webhooks: inbound webhooks that let external systems push events to a URL you control, and outbound webhook subscriptions that notify external systems when something changes. Both are configured from the Webhooks section in Bridge.

Inbound Webhooks

An inbound webhook gives you a public URL that any external system can POST to. Bridge verifies the request, maps the payload to platform fields, and routes the event to a connection, product API, or internal bus.

Creating an Inbound Webhook

  1. Go to Inbound Webhooks and click New.
  2. Enter a name and a slug. Your webhook URL will be https://api.theonestack.com/api/v1/bridge/hooks/in/{your-slug}.
  3. Choose a Verification Type:
    • None — accept any POST (use only for testing)
    • HMAC — Bridge generates a secret; the sending system must include an HMAC signature header
    • Basic Auth — Bridge accepts requests with a specific username/password
    • Bearer Token — Bridge accepts requests with a specific token in the Authorization header
  4. Define Field Mappings — which parts of the incoming JSON payload map to which platform fields. Use the payload path setting to target a nested object if the data you care about is not at the root.
  5. Choose a Routing Type:
    • Bus Event — publishes an event to the platform event bus for downstream automation
    • Connection — writes the data through an existing Bridge connection
    • Product API — calls a specific product API endpoint directly
  6. Save. Bridge generates the secret and shows it once. Copy it and configure it in the sending system.

Viewing Inbound Webhook Logs

Every request received is logged with the payload, headers, source IP, mapped payload, and routing result. To view logs, open the inbound webhook and click Logs. Use this to diagnose delivery failures or payload mapping problems.

Regenerating the Secret

If your HMAC or token secret is compromised, open the inbound webhook and click Regenerate Secret. Update the sending system with the new secret immediately, as the old one is invalidated.

Outbound Webhook Subscriptions

Outbound subscriptions tell Bridge to maintain a webhook subscription on an external platform so that the external system pushes events to Bridge as they happen. This enables near-real-time sync without polling.

Creating an Outbound Subscription

  1. Go to Webhooks > Subscriptions and click New Subscription.
  2. Select the connection (the external platform to subscribe to).
  3. Enter the endpoint URL that Bridge should receive events at (this is the /webhooks/receive path on the Bridge API).
  4. Enter the secret used to verify inbound payloads from the external platform.
  5. Select the event types to subscribe to.
  6. Save. Bridge registers the subscription with the external platform's API.

Replaying a Webhook Event

Inbound webhook events from outbound subscriptions are logged in Webhooks > Events. If processing failed (for example, due to a temporary platform outage), open the event and click Replay to reprocess it.

FAQ

What happens if the sending system posts to my inbound webhook URL and gets a 401? The verification secret does not match. Confirm the sending system is including the HMAC signature, Basic auth credentials, or Bearer token exactly as configured. If the secret was rotated, regenerate and reconfigure.

Can one inbound webhook receive payloads from multiple external systems? Technically yes, but it is better practice to create one inbound webhook per source so that field mappings and routing can be tailored to each system's payload format.

Do outbound subscriptions count against my rate limit? Inbound events received from external systems via subscriptions are processed by Bridge's internal routes, which are not subject to the same rate limits as the user-facing API. The external platform's own rate limits for creating and maintaining subscriptions still apply.

Related