Outbound Idempotency

Why You Would Use This

Without idempotency, the same business event can create multiple outbound webhook messages.

Typical cases:

• Your app retries because the API request timed out client-side.
• Queue workers re-run jobs after a crash/restart.
• You deploy failover logic that can submit the same event twice.

How It Works

For outbound sends, idempotency is controlled per send request using idempotency_key on POST /v1/webhooks/send.

{
  "endpoint_id": "YOUR_ENDPOINT_ID",
  "payload": {
    "event": "order.created",
    "order_id": "ord_123"
  },
  "idempotency_key": "order-123-created-v1"
}

Behavior:

• Same key + same endpoint + same payload: HookBridge does not create or send a second message. It returns the original message record.
• Same key + same endpoint + different payload: HookBridge rejects the request with conflict (409) and does not create a second message.
• No key: Every call is treated as new, so each call creates and sends a new message.

Console Workflow

1. Open Messages and filter by your endpoint/event.
2. Confirm that expected retries/re-sends are not creating duplicate messages.
3. If duplicates appear, update your producer to send stable idempotency_key values.
4. Re-test and verify only one message is created per business event.

API Workflow

API reference:

• Send webhook
• Get message

1) Send with idempotency key

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",
      "order_id": "ord_123"
    },
    "idempotency_key": "order-123-created-v1"
  }'

2) Verify the resulting message

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

Key Design Recommendations

• Derive keys from your source-of-truth event ID.
• Keep the same key across producer retries.
• Add a version suffix when event semantics change.
• Use endpoint-scoped keys if multiple endpoints receive the same event type.