Retrieving Events

Why You Would Use This

Retrieving events is the core workflow for pull endpoints. Instead of receiving webhooks pushed to your server, you pull events from HookBridge on your own schedule. This gives you full control over when and how events are processed.

The typical pattern is: list events to see what is available, get individual events to fetch their full payloads, and acknowledge events after successful processing.

How It Works

Events progress through three statuses:

• stored - The event has been received and is waiting to be retrieved.
• fetched - The event payload has been retrieved via the get event endpoint. HookBridge marks this automatically when you fetch an event’s payload.
• delivered - The event has been explicitly acknowledged via the ack endpoint.

Fetching an event marks it as fetched but does not mark it as delivered. You must call the acknowledge endpoint after processing. If your client crashes between fetching and processing, the event stays in fetched status and you can retrieve it again.

Acknowledging an event does not remove it right away. You can fetch its full payload and original headers again for 7 days after you acknowledge it, so you can recover if processing fails on your side. After that, the payload is permanently removed, but the event’s metadata (such as its status and timestamps) stays available until the retention period ends. If the retention period ends first, the event is removed sooner. To remove the payload before then, delete the event.

Console Workflow

1. Open Endpoints and switch to Pull.
2. Open a pull endpoint to view its events.
3. Use filters to narrow by event type, status, or date range.
4. Click an event to view its full payload and original headers.

API Workflow

API reference:

• List pull events
• Get pull event
• Acknowledge pull events

1) List events

List events returns metadata only (no payloads) for fast pagination across large event sets.

# List unacknowledged events (default: status=stored)
curl "https://api.hookbridge.io/v1/pull-endpoints/YOUR_PULL_ENDPOINT_ID/events" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Filter by event type
curl "https://api.hookbridge.io/v1/pull-endpoints/YOUR_PULL_ENDPOINT_ID/events?event_type=payment_intent.succeeded" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Filter by time range
curl "https://api.hookbridge.io/v1/pull-endpoints/YOUR_PULL_ENDPOINT_ID/events?since=2026-03-01T00:00:00Z&before=2026-03-02T00:00:00Z" \
  -H "Authorization: Bearer YOUR_API_KEY"

# List all events regardless of status
curl "https://api.hookbridge.io/v1/pull-endpoints/YOUR_PULL_ENDPOINT_ID/events?status=all&limit=500" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Paginate with cursor
curl "https://api.hookbridge.io/v1/pull-endpoints/YOUR_PULL_ENDPOINT_ID/events?cursor=NEXT_CURSOR_VALUE" \
  -H "Authorization: Bearer YOUR_API_KEY"

Query parameters:

Param	Type	Default	Description
status	string	stored	stored, fetched, delivered, or all
event_type	string	—	Exact match filter (e.g., payment_intent.succeeded)
since	ISO 8601	—	Events received after this timestamp (inclusive)
before	ISO 8601	—	Events received before this timestamp (exclusive)
limit	integer	100	Page size (1–1000)
cursor	string	—	Opaque cursor from a previous response

Events are returned in chronological order (oldest first).

2) Get a single event with payload

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

The response includes the full payload and original HTTP headers from the webhook provider. JSON payloads are embedded directly; non-JSON payloads are base64-encoded.

Returns 410 Gone with the error code PAYLOAD_DELETED if the event’s payload has been cleaned up, or MESSAGE_DELETED if you deleted the event. Returns 404 Not Found if the event no longer exists because its retention period has ended.

3) Acknowledge events

After processing events successfully, acknowledge them to mark them as delivered:

curl -X POST "https://api.hookbridge.io/v1/pull-endpoints/YOUR_PULL_ENDPOINT_ID/events/ack" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event_ids": ["EVENT_ID_1", "EVENT_ID_2", "EVENT_ID_3"]
  }'

• Accepts up to 1000 event IDs per request.
• Idempotent: acknowledging already-delivered events is a no-op for those events.
• All event IDs must belong to the specified pull endpoint.
• The response includes the count of newly acknowledged events.

Example: Batch Processing Workflow

A common pattern for batch consumers:

# 1. List unacknowledged events
EVENTS=$(curl -s "https://api.hookbridge.io/v1/pull-endpoints/YOUR_PULL_ENDPOINT_ID/events?limit=100" \
  -H "Authorization: Bearer YOUR_API_KEY")

# 2. For each event, fetch the full payload and process it
EVENT_ID="msg_01JQXYZ..."
curl -s "https://api.hookbridge.io/v1/pull-endpoints/YOUR_PULL_ENDPOINT_ID/events/$EVENT_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"

# 3. After processing a batch, acknowledge all at once
curl -X POST "https://api.hookbridge.io/v1/pull-endpoints/YOUR_PULL_ENDPOINT_ID/events/ack" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event_ids": ["msg_01JQX...", "msg_01JQY...", "msg_01JQZ..."]}'

Operational Tips

• Use status=stored (the default) when polling for new work. This returns only events that have not been fetched or acknowledged.
• Use status=fetched to find events that have been retrieved but not yet acknowledged. This is useful for detecting stalled consumers or events that need to be reprocessed.
• Acknowledge events in batches after processing rather than one at a time for better efficiency.
• If you need to reprocess events, use status=delivered or status=all to find previously acknowledged events, then fetch each one by ID within 7 days of acknowledging it. If you need a payload for longer, save your own copy before acknowledging.
• Use event_type filtering to build consumers that only process specific event types from the same endpoint.
• Use since to avoid re-scanning old events on each poll cycle. Track the received_at of the last event you processed and pass it as since on the next request.