Bridge to Outbound
A bridge is a destination that publishes each delivery as an outbound event. Point a route at a bridge and every webhook it forwards is sent on to the outbound endpoints subscribed to that event type, with outbound's signing, retries and delivery logs.
Use it to turn a vendor's webhooks into your own: receive Stripe's invoice.paid, and your
customers get billing.invoice.paid from you, on the endpoints they subscribed.
Bridges are available on every plan.
Setting Up a Bridge
- Create the outbound event type the bridge will publish (Outbound Webhooks → Event Types), and make sure it is enabled.
- Create a destination of type Outbound Bridge (
"type": "bridge") and choose where its event type comes from. - Point a route at it, from the source whose webhooks you want to publish.
A bridge has no URL, headers, auth or static IP. The API refuses them on a bridge with 400. Throttling works as on any destination.
Event Type
eventTypeSource | Publishes | Fields |
|---|---|---|
fixed | The same event type for every delivery | eventType: an existing, enabled event type |
field | The type named in each payload | eventTypeField: a dot path into the payload, at most 5 segments (e.g. data.type). eventTypePrefix (optional): put in front of the value (e.g. stripe.) |
In field mode the prefix plus the field's value must be a valid event type name, and that type must
exist and be enabled when the delivery publishes. With "eventTypePrefix": "stripe." and a payload
whose type is invoice.paid, the bridge publishes stripe.invoice.paid. The field's value may be a
non-empty string or a number.
Each mode's fields are refused in the other mode, and any other key is refused, with 400
Invalid bridge configuration.
Applications
By default a bridge publishes to the subscribed endpoints of every application. Set applicationId to
publish to one application's endpoints only.
{
"name": "Stripe to customers",
"slug": "stripe-to-customers",
"type": "bridge",
"config": {
"eventTypeSource": "field",
"eventTypeField": "type",
"eventTypePrefix": "stripe.",
"applicationId": "33333333-3333-4333-8333-333333333333"
}
}The Sender Check
A bridge sends what it receives to your customers' endpoints as your event. So by default it publishes only events whose source verified the sender:
- a valid signature made with the source's own signing secret, or
- on a source with no provider, Custom HMAC or Generic, an IP allowlist with no range wider than /16 (IPv4) or /48 (IPv6).
These don't count:
- AWS SNS and Wise signatures. Any AWS or Wise account can make a valid one.
- An IP allowlist on a source with any other provider, such as Stripe or GitHub. That source has to verify a signature instead.
- An IP allowlist on a source made from a catalog template that Hookbase has no built-in
verification for: Salesforce, Plaid, Microsoft Teams, Mollie, Docker Hub and DigitalOcean. Such a
source is saved as Custom HMAC, and it records the template it came from in
catalogProvider. A vendor sends every customer's webhooks from the same published IP ranges, so those ranges don't show that an event came from your account. - An unsigned request to a source with no secret.
Hookbase can't tell whose addresses an allowlist names, so on a custom source you make yourself, list
only addresses your sender alone uses. Sources made from those templates before November 2026 have no
catalogProvider, so their allowlist still counts: check what it lists, or make the source again from
the template.
An event that fails the check is refused with 403, and nothing is published. To publish events a
source can't verify, set allowUnverifiedSources: true on the bridge.
Warning
allowUnverifiedSources lets anyone who can reach the source URL publish to your customers
With it on, an unsigned or forged request to a source routed to the bridge goes out to your customers' endpoints as a real event. Turn it on only for a source that can't be verified, and keep the source URL private.
The check uses the verdict recorded when the event arrived, so a source given a secret later doesn't
vouch for events nothing checked. Events received before bridge support shipped, on November 11, 2026,
have no recorded verdict: a replay of one into a bridge is accepted, and its delivery then fails with
403 unless allowUnverifiedSources is on.
Loop Protection
An outbound endpoint can be a Hookbase source, including one routed to the same bridge. To stop a
loop, every bridged event carries a hop count in the X-Hookbase-Hop header of its outbound
deliveries, and ingest keeps it. Inbound deliveries to HTTP destinations pass the count on too.
A bridge refuses an event that has already crossed 3 bridges, with 508. A loop therefore ends after three outbound events.
When a Bridge Delivery Fails
A bridge failure is final. It isn't retried, doesn't fail over and doesn't count toward the route's circuit breaker, so one bad payload doesn't stop the route's other events. The delivery shows the status and reason, and you can replay it once the cause is fixed.
| Status | Cause |
|---|---|
| 400 | The bridge's config is invalid |
| 403 | The sender wasn't verified (see The Sender Check) |
| 404 | The event type doesn't exist or is disabled |
| 413 | The payload is larger than the outbound payload limit |
| 422 | The payload isn't a JSON object, the event type field is missing or unusable, or the payload fails the event type's schema |
| 429 | Your outbound message quota is used up |
| 508 | Loop detected: the event has already crossed 3 bridges |
A successful delivery records status 200 and a body with the outbound event's ID, its type and the number of messages queued (and held). The event debugger shows it as Published outbound event, and each outbound message links back to the inbound event under Bridged from inbound event.
A failure inside Hookbase itself (database or queue) is different: the delivery is retried as usual.
Idempotency
Every retry of one delivery publishes at most one outbound event. A replay or a DLQ retry is a new delivery, so it publishes again.
Billing and Limits
A bridge counts on both sides. The delivery counts as an inbound delivery, and each message it queues counts toward your outbound message quota. When the outbound quota is used up, bridge deliveries fail with 429.
Publishing through a bridge doesn't go through the send-event API, so its per-minute rate limit doesn't apply. Use the destination's throttle to limit the rate.
Permissions
A bridge publishes outbound events, so these need the events:send permission as well as the
usual one:
- creating a bridge, and any change to one,
- importing a bridge,
- creating a route into a bridge, or changing the source, destination, failovers or transform of a route that delivers to one,
- replaying into a bridge with a destination override, or with an edited payload or transform (for an edited payload, this includes a route whose failover is a bridge),
- sending a test event from a source routed to a bridge (Tools → Testing, or
POST /api/testing/sources/{id}/test).
Without it the API answers 403 Permission denied: events:send.
Checking a Bridge
- Test. A bridge's Test (
POST /api/destinations/{id}/test) is a dry run. It resolves the event type from a sample payload, checks that the type exists and is enabled, and counts the endpoints subscribed to it. Nothing is published. Send your own sample payload from Tools → Testing. The count is an upper bound: it doesn't apply subscription filters or circuit state. - Simulator. The source simulator shows "Would publish outbound event…" or why the bridge would fail. It doesn't model the sender check, the hop count or the quota.
Warning
A source test event goes through real ingest, so a route from that source to a bridge can publish it to your customers' endpoints. Use the bridge's Test or the simulator to check a bridge without publishing.