Pull Idempotency

Why You Would Use This

Many providers retry webhook deliveries. Without idempotency controls, the same upstream event can be stored multiple times in your pull endpoint.

Pull endpoint idempotency lets you define which incoming headers HookBridge should use as the dedupe identity for that endpoint.

How It Works

Idempotency dedupe is configured per endpoint using idempotency_header_names.

HookBridge builds an idempotency key from the configured header list (in order).

When the same key is received again for the same pull endpoint:

• HookBridge does not store a duplicate event.
• HookBridge returns an ingest success response to the sender with the original event ID.

Console Workflow

1. Open Endpoints -> Pull.
2. Open your pull endpoint.
3. Set idempotency header names based on provider docs.
4. Save changes.
5. Send duplicate test events from provider tools and confirm dedupe behavior.

API Workflow

API reference:

• Get pull endpoint
• Update pull endpoint

Configure idempotency headers

curl -X PATCH https://api.hookbridge.io/v1/pull-endpoints/YOUR_PULL_ENDPOINT_ID \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "idempotency_header_names": ["Idempotency-Key", "X-Event-ID"]
  }'

Validate endpoint config

curl https://api.hookbridge.io/v1/pull-endpoints/YOUR_PULL_ENDPOINT_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

Configuration Tips

• Prefer provider-native immutable event IDs.
• Include fallback header names only if they are stable and consistently present.
• Keep header order intentional because idempotency_header_names is ordered.