Getting Started: Send Webhooks

This guide is for implementers who want to send webhooks through HookBridge quickly, then monitor and recover deliveries when needed.

Prerequisites

• HookBridge account at app.hookbridge.io
• Access to the HookBridge Console
• A destination URL for the system that should receive your webhooks (must be https://)

Step 1: Create an API Key

Console

1. Open API Keys.
2. Click Create API Key.
3. Optionally add a label.
4. Copy and store the key securely. It is shown only once.

API

If you already have an API key, you can create additional keys via API:

curl -X POST https://api.hookbridge.io/v1/api-keys \
  -H "Authorization: Bearer YOUR_EXISTING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "backend-service"
  }'

Use the returned key as:

Authorization: Bearer wrc_xxxxxxxxxxxxxxxxxxxx

Step 2: Create an Outbound Endpoint

Console

1. Open Endpoints.
2. Stay on the Outbound tab.
3. Click Create Endpoint.
4. Enter your destination URL and optional description.
5. Save the endpoint.
6. Copy the endpoint ID (ep_...) for sending.
7. Store the signing secret shown on creation.

API

curl

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

Node.js

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

const client = new HookBridge({ apiKey: process.env.HOOKBRIDGE_API_KEY });

const endpoint = await client.createEndpoint({
  url: 'https://your-app.com/webhooks',
  description: 'Production destination',
});

console.log(endpoint.id);

Python

from hookbridge import HookBridge

client = HookBridge(api_key="YOUR_API_KEY")
endpoint = client.create_endpoint(
    url="https://your-app.com/webhooks",
    description="Production destination"
)

print(endpoint.id)

Go

package main

import (
    "context"
    "fmt"
    "log"

    hookbridge "github.com/hookbridge/hookbridge-go"
)

func main() {
    client, err := hookbridge.NewClient("YOUR_API_KEY")
    if err != nil {
        log.Fatal(err)
    }
    desc := "Production destination"
    endpoint, err := client.CreateEndpoint(context.Background(), hookbridge.CreateEndpointRequest{
        URL:         "https://your-app.com/webhooks",
        Description: &desc,
    })
    if err != nil {
        log.Fatal(err)
    }

    fmt.Println(endpoint.ID)
}

Ruby

require "hookbridge"

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

endpoint = client.create_endpoint(
  url: "https://your-app.com/webhooks",
  description: "Production destination"
)

puts endpoint.id

PHP

<?php

use HookBridge\HookBridge;

$client = new HookBridge('YOUR_API_KEY');

$endpoint = $client->createEndpoint(
    url: 'https://your-app.com/webhooks',
    description: 'Production destination',
);

echo $endpoint->id . PHP_EOL;

Step 3: Send a Test Webhook

Console

1. Open Endpoints and choose your outbound endpoint.
2. Copy the endpoint ID (ep_...).
3. Use that endpoint ID in the API request below.
4. Open Messages to confirm delivery attempts and capture the created message ID.

API

curl

curl -X POST https://send.hookbridge.io/v1/webhooks/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "endpoint_id": "YOUR_ENDPOINT_ID",
    "payload": {
      "event": "order.created",
      "data": {
        "order_id": "order_789",
        "amount": 9999,
        "currency": "usd"
      }
    },
    "idempotency_key": "order-789-created-v1"
  }'

Node.js

const result = await client.send({
  endpointId: 'YOUR_ENDPOINT_ID',
  payload: {
    event: 'order.created',
    data: { orderId: 'order_789', amount: 9999, currency: 'usd' }
  },
  idempotencyKey: 'order-789-created-v1'
});

console.log(result.messageId);

Python

result = client.send(
    endpoint_id="YOUR_ENDPOINT_ID",
    payload={
        "event": "order.created",
        "data": {"order_id": "order_789", "amount": 9999, "currency": "usd"}
    },
    idempotency_key="order-789-created-v1"
)

print(result.message_id)

Go

result, _ := client.Send(context.Background(), hookbridge.SendRequest{
    EndpointID: "YOUR_ENDPOINT_ID",
    Payload: map[string]any{
        "event": "order.created",
        "data": map[string]any{
            "order_id": "order_789",
            "amount":   9999,
            "currency": "usd",
        },
    },
    IdempotencyKey: "order-789-created-v1",
})

fmt.Println(result.MessageID)

Ruby

result = client.send(
  endpoint_id: "YOUR_ENDPOINT_ID",
  payload: {
    event: "order.created",
    data: { order_id: "order_789", amount: 9999, currency: "usd" }
  },
  idempotency_key: "order-789-created-v1"
)

puts result.message_id

PHP

$result = $client->send(
    endpointId: 'YOUR_ENDPOINT_ID',
    payload: [
        'event' => 'order.created',
        'data' => [
            'order_id' => 'order_789',
            'amount' => 9999,
            'currency' => 'usd',
        ],
    ],
    idempotencyKey: 'order-789-created-v1',
);

echo $result->messageId . PHP_EOL;

Step 4: Verify Delivery and Recover Failures

Console

1. Open Messages to review recent deliveries.
2. Filter by endpoint or status (succeeded, pending_retry, failed_permanent).
3. Open message details for attempt history and response information.
4. For failures, use replay/retry actions from the message workflow.

API

Use the message_id returned by the send response (for example data.message_id):

# Fetch one message
curl https://api.hookbridge.io/v1/messages/YOUR_MESSAGE_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

# Retry immediately
curl -X POST https://api.hookbridge.io/v1/messages/YOUR_MESSAGE_ID/retry-now \
  -H "Authorization: Bearer YOUR_API_KEY"

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

Next Steps

• Outbound Overview
• Outbound Signature Verification
• Getting Started: Receive Webhooks