Getting Started: Receive Webhooks

This guide is for implementers who want HookBridge to ingest webhooks from external providers, verify them, and forward them to internal destinations reliably.

Prerequisites

• HookBridge account at app.hookbridge.io
• A selected project in the console
• A destination forwarding URL where your system accepts events (must be https://)

How Inbound Works

1. You create an inbound endpoint in HookBridge.
2. HookBridge gives you an ingest_url.
3. External providers POST to that ingest_url.
4. HookBridge verifies requests using your configured checks.
5. Accepted events are forwarded to your configured destination URL.

Step 1: Create an Inbound Endpoint

Console

1. Open Endpoints.
2. Switch to the Inbound tab.
3. Click Create Inbound Endpoint.
4. Set a name and forwarding URL.
5. Save and copy the generated ingest_url.

API

curl

curl -X POST https://api.hookbridge.io/v1/inbound-endpoints \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Stripe webhooks",
    "url": "https://your-app.com/inbound/stripe"
  }'

Node.js

import { HookBridge } from '@hookbridge/sdk';

const client = new HookBridge({ apiKey: 'YOUR_API_KEY' });

const inbound = await client.createInboundEndpoint({
  url: 'https://your-app.com/inbound/stripe',
  name: 'Stripe webhooks'
});

console.log(inbound.ingestUrl);

Python

from hookbridge import HookBridge

client = HookBridge(api_key="YOUR_API_KEY")

inbound = client.create_inbound_endpoint(
    url="https://your-app.com/inbound/stripe",
    name="Stripe webhooks"
)

print(inbound.ingest_url)

Go

client, _ := hookbridge.NewClient("YOUR_API_KEY")

name := "Stripe webhooks"
inbound, _ := client.CreateInboundEndpoint(ctx, hookbridge.CreateInboundEndpointRequest{
    URL:  "https://your-app.com/inbound/stripe",
    Name: &name,
})

fmt.Println(inbound.IngestURL)

Ruby

require "hookbridge"

client = HookBridge.new(api_key: "YOUR_API_KEY")

inbound = client.create_inbound_endpoint(
  url: "https://your-app.com/inbound/stripe",
  name: "Stripe webhooks"
)

puts inbound.ingest_url

PHP

<?php

use HookBridge\HookBridge;

$client = new HookBridge('YOUR_API_KEY');

$inbound = $client->createInboundEndpoint(
    url: 'https://your-app.com/inbound/stripe',
    name: 'Stripe webhooks',
);

echo $inbound->ingestUrl . PHP_EOL;

Store the ingest_url and secret_token from the response. They are only returned once.

Step 2: Configure Verification Options

HookBridge supports all inbound verification options shown in the console.

Console

1. Open the inbound endpoint.
2. Configure one or more verification modes:
   • Static token
   • HMAC signature verification
   • IP allowlist
3. Save updates.

API

curl -X PATCH https://api.hookbridge.io/v1/inbound-endpoints/YOUR_INBOUND_ENDPOINT_ID \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "verify_static_token": true,
    "token_header_name": "X-Webhook-Token",
    "token_value": "my-secret-token",
    "verify_hmac": true,
    "hmac_header_name": "Stripe-Signature",
    "hmac_secret": "whsec_abc123",
    "timestamp_header_name": "X-Webhook-Timestamp",
    "timestamp_ttl_seconds": 300,
    "verify_ip_allowlist": true,
    "allowed_cidrs": ["203.0.113.0/24"],
    "idempotency_header_names": ["Idempotency-Key"],
    "signing_enabled": true
  }'

Step 3: Point Provider Traffic to HookBridge

Console

1. Copy the endpoint ingest_url from inbound endpoint details.
2. In your provider system (Stripe, GitHub, partner system, etc.), set webhook destination to that ingest_url.
3. Send a test event from the provider.

API

Provider systems should send HTTP POST requests to:

https://receive.hookbridge.io/v1/webhooks/receive/{inbound_endpoint_id}/{secret_token}

Example test request:

curl -X POST "https://receive.hookbridge.io/v1/webhooks/receive/YOUR_INBOUND_ENDPOINT_ID/YOUR_SECRET_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Token: my-secret-token" \
  -d '{"event":"payment.succeeded","id":"evt_123"}'

Step 4: Monitor Inbound Activity

Console

1. Open Dashboard and Messages to view delivery status.
2. Open the inbound endpoint detail page for endpoint-specific activity.
3. Check rejections when verification fails.

API

# Inbound logs
curl "https://api.hookbridge.io/v1/inbound-logs?limit=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Inbound metrics
curl "https://api.hookbridge.io/v1/inbound-metrics?window=24h" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Rejections
curl "https://api.hookbridge.io/v1/inbound-rejections?limit=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

Step 5: Pause/Resume and Replay

Console

1. Open the inbound endpoint details page.
2. Use Pause during maintenance windows.
3. Use Resume when ready to accept traffic.
4. Replay failed inbound messages from endpoint/message workflows.

API

Use values from your created inbound endpoint:

• YOUR_INBOUND_ENDPOINT_ID: from the endpoint record
• YOUR_INBOUND_MESSAGE_ID: from inbound logs/message detail

# Pause endpoint
curl -X POST https://api.hookbridge.io/v1/inbound-endpoints/YOUR_INBOUND_ENDPOINT_ID/pause \
  -H "Authorization: Bearer YOUR_API_KEY"

# Resume endpoint
curl -X POST https://api.hookbridge.io/v1/inbound-endpoints/YOUR_INBOUND_ENDPOINT_ID/resume \
  -H "Authorization: Bearer YOUR_API_KEY"

# Replay one message
curl -X POST https://api.hookbridge.io/v1/inbound-messages/YOUR_INBOUND_MESSAGE_ID/replay \
  -H "Authorization: Bearer YOUR_API_KEY"

# Replay many by status
curl -X POST "https://api.hookbridge.io/v1/inbound-messages/replay-all?status=failed_permanent&limit=100" \
  -H "Authorization: Bearer YOUR_API_KEY"

Next Steps

• Inbound Overview
• Inbound Verification Options
• Getting Started: Send Webhooks