1. Webhooks
CrossFX Payment APIs
  • Guides
    • CrossFX API Documentation
    • Support & Contact
    • API Basics
    • Authentication Guide
    • FX Rates
      • FX Rates Guide
    • Corridors
      • Supported Corridors Guide
    • Banks
      • Fetching Banks List Guide
      • Fetching Bank Branches Guide
    • Sanctions
      • Sanctions Screening Guide
    • Beneficiaries
      • Create Beneficiary Guide
      • Get Beneficiary Guide
    • Transfers
      • Generate Quote Guide
      • Confirm Transfer Guide
      • Get Transfer Status Guide
    • Crypto Deposit Address
      • Crypto Deposit Address Guide
    • Payments
      • Initiate Deposit Guide
      • Initiate Payout Guide
    • Webhooks
      • Webhooks Guide
      • Webhook Subscriptions Guide
      • Webhook Events Guide
      • Webhook Delivery Attempts Guide
    • Sandbox
      • Sandbox Data & Testing Guide
  1. Webhooks

Webhook Events Guide

Overview#

An event is the platform's record of one thing that happened, together with the exact signed envelope that was sent for it. The event survives whether or not the delivery did, so it is where you look when a webhook never reached you. This page covers searching events, reading one back in full, and requeuing one whose retries ran out.

Key features#

The sent envelope is kept: payload holds what was signed and posted, so you can process an event you never received
Delivery state per event: status summarises the outcome across every subscription that matched the event
Filtering that narrows: by delivery state, event type, source object, or free text over the id, public_id, idempotency_key and event_type_code
Replay for exhausted events: an event in dead_letter can be put back on the queue once your endpoint is healthy

Use cases#

Reconcile against your own event log after an outage and find what you missed
Confirm whether an event you never saw was actually raised, or never happened
Requeue everything that dead-lettered while your endpoint was down
Rebuild your state from payload without waiting for a redelivery

Prerequisites#

A valid bearer token. See the Authentication Guide.
At least one subscription set to active. See the Webhook Subscriptions Guide. A subscription still in pending_verification produces no events to find.
The paging and filtering contract shared by every search endpoint. See the API Basics.

API#

Search Webhook Events
POST /api/v1/webhooks/events/search
Paginated search across the events raised for your organisation.
Get Webhook Event
GET /api/v1/webhooks/events/{event_id}
One event in full, including the payload that was signed and sent.
Replay Webhook Event
POST /api/v1/webhooks/events/{event_id}/replay
Puts a dead-lettered event back on the delivery queue.
NOTE
Send a filters object to search, and you get back a page of events. The item and replay routes take the integer id from a search row.

Business rules#

partially_delivered is a summary across subscriptions, not one endpoint's result. It means at least one subscription accepted the event and at least one did not. To find out which, read the delivery attempts for that event.
Only an event in dead_letter can be replayed. Every other state is refused. An event reaches dead_letter when its retries are exhausted.
Replay is not idempotent. Each call queues another round of deliveries. Call it twice and your endpoint receives the event twice.
A 202 means queued. Check the delivery attempts for the event to see more details.
Replay fans out to every subscription matching the event type, including any that already received the event successfully.

Errors#

Every error below returns the platform envelope, with error first and error_id last. Quote error_id when you contact support.
HTTPcodeTriggerWhat you do
422VALIDATION_FAILEDA filter was sent as a single value rather than a list, an unknown filter key was sent, or sort_by is outside id, created_at, updated_atRead error.json for the field. Send every filter as a list.
400BAD_REQUESTReplay was called on an event that is not in dead_letterRead the event first. Only an event whose retries are exhausted can be replayed.
404NOT_FOUNDNo event matches the id, or it belongs to another organisationTake the id from a search result.
401The Authorization header is missing, malformed, or the token has expiredRequest a new token and retry. The body is { "message": "Unauthorized" }.
429RATE_LIMIT_EXCEEDEDToo many requestsBack off and retry.
500INTERNAL_ERRORThe platform failed to answerRetry once, then contact support with error_id.
INFO
A search that returns an empty page is a result. Paging past the end of the collection returns 200 with an empty list and the true total.

Related#

Webhooks Guide
Signature verification, retry behaviour, and every event payload.
Support & Contact
What to send us when an event never arrives.
Modified at 2026-09-08 10:39:29
Previous
Webhook Subscriptions Guide
Next
Webhook Delivery Attempts Guide
Built with