Event Type Extraction

Why You Would Use This

Event type extraction lets HookBridge automatically tag each incoming webhook with an event type (e.g., payment_intent.succeeded, pull_request). Once events are tagged, you can filter by event type when retrieving them, making it easy to pull only the events your consumer cares about.

Without extraction configured, events are still stored but have no event type attached. You can always retrieve all events regardless.

How It Works

You configure two settings on the pull endpoint:

• event_type_source: where to find the event type, either "body" (JSON payload) or "header" (HTTP header).
• event_type_path: the specific field or header name to extract from.

When a webhook arrives, HookBridge extracts the event type and stores it with the event. If extraction fails (field missing, malformed payload), the event is still stored with a null event type. The webhook is never rejected because of extraction failure.

Common Provider Patterns

Provider	Source	Path	Example Value
Stripe	body	type	payment_intent.succeeded
GitHub	header	X-GitHub-Event	pull_request
Shopify	header	X-Shopify-Topic	orders/create
Twilio	body	type	com.twilio.messaging.inbound-message.received

For nested JSON fields, use dot notation: event.type, data.object.type.

Console Workflow

1. Open Endpoints and switch to Pull.
2. Open the pull endpoint or create a new one.
3. Set the Event Type Source to Body or Header.
4. Set the Event Type Path to the field name or header name.
5. Save changes.

API Workflow

API reference:

• Create pull endpoint
• Update pull endpoint

Configure at creation (body extraction)

curl -X POST https://api.hookbridge.io/v1/pull-endpoints \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Stripe Events",
    "event_type_source": "body",
    "event_type_path": "type"
  }'

Configure at creation (header extraction)

curl -X POST https://api.hookbridge.io/v1/pull-endpoints \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "GitHub Events",
    "event_type_source": "header",
    "event_type_path": "X-GitHub-Event"
  }'

Update extraction config

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 '{
    "event_type_source": "body",
    "event_type_path": "data.event_type"
  }'

Remove extraction config

Set event_type_source to an empty string to clear extraction:

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 '{
    "event_type_source": ""
  }'

Configuration Tips

• Use body extraction for providers that include a type field in the JSON payload (most common).
• Use header extraction for providers that put event types in HTTP headers (e.g., GitHub’s X-GitHub-Event).
• Dot-separated paths support nested fields: "event.type" extracts from {"event": {"type": "order.created"}}.
• If extraction fails on a specific webhook, the event is stored with a null event type. Filter for events without a type to identify extraction issues.