Deleting Messages

Why You Would Use This

Deletion gives you control over payloads that should no longer exist in HookBridge before retention would naturally expire. Common reasons:

• A payload contains sensitive data that was sent in error.
• A payload is corrupted and you want to free the idempotency key so you can resend a corrected version.
• A privacy or compliance requirement forces you to remove specific payloads on request.

Deletion works for outbound messages, inbound messages, and pull events. The rules and response shapes are consistent across the three families.

What Is Deleted

When a delete request succeeds, HookBridge removes access to the payload immediately and cleans up the stored payload shortly after:

• The payload becomes unreachable. Any response that would have returned the payload, payload URL, or payload body returns nothing in those fields from this point on. This takes effect the moment your delete request commits.
• The stored payload is cleaned up. The payload is removed from HookBridge’s storage asynchronously, typically within the next cleanup cycle. Once removed, it cannot be recovered.
• Any scheduled retry is cancelled. A pending retry will not fire after deletion. An attempt that was already in flight at the exact moment of the delete may complete, but no further attempts will be scheduled.
• The idempotency key is released. If the message was sent with an idempotency key, that key becomes available again so a subsequent send with the same (endpoint, idempotency_key) pair can succeed.

What Is Not Deleted

The message record and its history are preserved so you can still audit what happened:

• The message row remains. It continues to appear in logs and message lists.
• The original status is kept. A message that was succeeded before deletion stays succeeded afterward. A failed_permanent message remains failed_permanent.
• Delivery attempt history is kept. Every attempt timestamp, response code, response header, and error message remains visible.
• Message metadata is kept. Timestamps (created_at, received_at), endpoint association, headers, event type (for pull), and other metadata remain available.
• Actor information is recorded. Each deleted message records who performed the deletion (a user or an API key) and the deletion timestamp.

Behavior After Deletion

Once a message is deleted:

• Replay, cancel, and retry-now return 410 Gone with the error code MESSAGE_DELETED. There is no payload left to act on.
• Pull fetches silently skip deleted events. Consumers pulling the next batch of events never see them.
• List endpoints exclude deleted messages by default. Pass deleted=only to see only deleted messages, or deleted=include to see both live and deleted rows.
• Deleting again is a no-op. A repeat delete returns 200 with already_deleted: true and the original deleted_at timestamp.

Console Workflow

1. Open Messages and locate the message to delete. The same flow applies to outbound, inbound, and pull.
2. Click the message to open its detail view.
3. Click Delete and confirm in the modal.
4. After deletion, the detail view shows a Deleted banner with the deletion timestamp and the user or API key that performed the action. Replay, Cancel, and Retry Now are disabled with a “Payload deleted” tooltip.

To delete several messages at once, multi-select rows in the message list and use Delete selected. The bulk list action accepts up to 100 messages per request.

API Workflow

API reference:

• Delete message
• Batch delete messages
• Delete all messages
• Delete inbound message
• Batch delete inbound messages
• Delete all inbound messages
• Delete pull event
• Batch delete pull events
• Delete all pull events

1) Delete a single message

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

# Inbound
curl -X DELETE https://api.hookbridge.io/v1/inbound-messages/YOUR_INBOUND_MESSAGE_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

# Pull event
curl -X DELETE https://api.hookbridge.io/v1/pull-endpoints/YOUR_PULL_ENDPOINT_ID/events/YOUR_EVENT_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

The response includes the deletion timestamp and an already_deleted flag. Deleting an already-deleted message returns 200 with already_deleted: true and the original timestamp.

2) Delete a batch of specific messages by ID

curl -X POST https://api.hookbridge.io/v1/messages/delete-batch \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message_ids": ["MESSAGE_ID_1", "MESSAGE_ID_2"]}'

• Accepts up to 100 IDs per request. Over the cap returns 400 TOO_MANY_IDS.
• Each ID is reported back with an outcome of deleted, already_deleted, or not_found. The batch never fails because of a single bad ID.
• Inbound uses /v1/inbound-messages/delete-batch. Pull uses /v1/pull-endpoints/YOUR_PULL_ENDPOINT_ID/events/delete-batch.

3) Delete many messages by filter

# Outbound: filter by status and endpoint
curl -X POST "https://api.hookbridge.io/v1/messages/delete-all?status=failed_permanent&endpoint_id=YOUR_ENDPOINT_ID&limit=1000" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Inbound: filter by inbound endpoint and time window
curl -X POST "https://api.hookbridge.io/v1/inbound-messages/delete-all?inbound_endpoint_id=YOUR_INBOUND_ENDPOINT_ID&received_before=2026-03-01T00:00:00Z" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Pull: filter by event type
curl -X POST "https://api.hookbridge.io/v1/pull-endpoints/YOUR_PULL_ENDPOINT_ID/events/delete-all?event_type=payment_intent.succeeded&limit=500" \
  -H "Authorization: Bearer YOUR_API_KEY"

Filters per family:

Family	Endpoint filter	Time filters	Extra filters
Outbound	endpoint_id	created_after, created_before	status
Inbound	inbound_endpoint_id	received_after, received_before	status
Pull	path-scoped on {pull_endpoint_id}	received_after, received_before	status, event_type

All three accept limit (default and max 1000).

The response returns the total deleted count and the list of IDs that were deleted. On a mid-call error, the response is still 200 with the subset of IDs that committed plus an error object:

• PARTIAL_DELETE_FAILURE — some rows were deleted before the error. Re-run the request to continue.
• DELETE_FAILED — the call errored before any rows committed.

Operational Tips

• Deletion is permanent. There is no undelete, no restore window.
• If you need to preserve delivery records for audit after deleting payloads, use exports first. Exported records include the payload at the time of export.
• Use delete-batch when you already have a specific list of IDs from a prior logs query.
• Use delete-all with a tight status + time-window combination for incident cleanup. Run it repeatedly until deleted comes back as 0 to drain a large match set.
• A deleted message still appears in the default list view only if you pass deleted=include. If you are checking that a cleanup ran, use deleted=only to see the deleted set directly.
• To re-send a message with the same idempotency key, delete the original first — the key is released as part of the delete.