Webhook subscriptions tell OpenFX where to send event notifications and which event types you care about. Each subscription targets a single HTTPS endpoint URL and can filter events to a specific set of types or receive everything with the wildcard ["*"].

​
Creating a subscription

To start receiving webhooks, create a subscription with POST /webhooks/subscriptions. You need to provide your endpoint URL and the event types you want to receive. 
curl -X POST https://sandbox.api.openfx.com/v1/webhooks/subscriptions \
  -H "Authorization: Bearer sk_sandbox_your_api_key" \
  -H "X-Signature: <computed-signature>" \
  -H "X-Timestamp: 1740500000" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440020" \
  -d '{
    "url": "https://your-app.example.com/webhooks/openfx",
    "eventTypes": [
      "payment.completed",
      "payment.failed",
      "payment.returned",
      "customer.kyb_status_changed"
    ],
    "description": "Payment and onboarding notifications"
  }'
The response is a WebhookSubscriptionCreatedResponse that includes all subscription fields plus the signingSecret: 
{
  "id": "wsub_01953e1a5f4b700a",
  "url": "https://your-app.example.com/webhooks/openfx",
  "eventTypes": [
    "payment.completed",
    "payment.failed",
    "payment.returned",
    "customer.kyb_status_changed"
  ],
  "status": "active",
  "signingSecret": "whsec_a1b2c3d4e5f6...",
  "description": "Payment and onboarding notifications",
  "createdAt": "2026-02-23T12:00:00Z",
  "updatedAt": "2026-02-23T12:00:00Z"
}
The signingSecret is only returned at creation time and when you rotate the secret. It cannot be retrieved again. Store it in a secrets manager (e.g., AWS Secrets Manager, HashiCorp Vault, environment variable) immediately. If you lose it, you must rotate to get a new one.

​
Selecting event types

You can subscribe to specific event types or use the wildcard to receive everything.

​
Specific event types

Pass an array of event type strings. Only events matching these types will be delivered to your endpoint: 
{
  "eventTypes": [
    "payment.completed",
    "payment.failed",
    "customer.kyb_status_changed"
  ]
}

​
Wildcard subscription

Use ["*"] to subscribe to all current and future event types. This is useful for development and debugging, but in production you should subscribe only to the events your application processes: 
{
  "eventTypes": ["*"]
}
During development, start with ["*"] so you can see the full event stream. Before going to production, narrow your subscription to only the event types your application handles. This reduces unnecessary webhook traffic and simplifies your processing logic.
Use caseRecommended event types
Payment processingpayment.created, payment.processing, payment.completed, payment.failed, payment.returned
Onboardingcustomer.created, customer.status_changed, customer.kyb_status_changed
FX operationsconversion.completed, conversion.failed
Collectionscollection.created, collection.completed, collection.returned, collection.failed
Reconciliationtransaction.created
Full audit trail["*"]

​
Subscription statuses

A webhook subscription moves through three possible statuses:
StatusDescription
activeThe subscription is receiving events. This is the initial status.
suspendedThe subscription is temporarily paused. This can happen automatically after repeated delivery failures, or you can set it manually via PATCH. Events are not delivered while suspended.
disabledThe subscription is permanently disabled. No events are delivered.
When a subscription is suspended due to delivery failures, fix the issue with your endpoint, then reactivate the subscription by updating its status to active. Any events that occurred while the subscription was suspended can be recovered through the Events API (GET /events).

​
Updating a subscription

Use PATCH /webhooks/subscriptions/{webhookSubscriptionId} to update the URL, event types, status, or description of an existing subscription. 
curl -X PATCH https://sandbox.api.openfx.com/v1/webhooks/subscriptions/wsub_01953e1a5f4b700a \
  -H "Authorization: Bearer sk_sandbox_your_api_key" \
  -H "X-Signature: <computed-signature>" \
  -H "X-Timestamp: 1740500000" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440021" \
  -d '{
    "eventTypes": [
      "payment.completed",
      "payment.failed",
      "payment.returned",
      "payment.reversed",
      "customer.kyb_status_changed"
    ],
    "description": "Payment and onboarding notifications"
  }'

​
Reactivating a suspended subscription

If your subscription was suspended due to delivery failures, reactivate it after fixing your endpoint: 
curl -X PATCH https://sandbox.api.openfx.com/v1/webhooks/subscriptions/wsub_01953e1a5f4b700a \
  -H "Authorization: Bearer sk_sandbox_your_api_key" \
  -H "X-Signature: <computed-signature>" \
  -H "X-Timestamp: 1740500000" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440022" \
  -d '{ "status": "active" }'

​
Deleting a subscription

Use DELETE /webhooks/subscriptions/{webhookSubscriptionId} to permanently remove a subscription. This action cannot be undone. 
curl -X DELETE https://sandbox.api.openfx.com/v1/webhooks/subscriptions/wsub_01953e1a5f4b700a \
  -H "Authorization: Bearer sk_sandbox_your_api_key" \
  -H "X-Signature: <computed-signature>" \
  -H "X-Timestamp: 1740500000" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440023"

​
Testing your webhook endpoint

Before relying on webhooks in production, verify your endpoint works correctly. Use the test endpoint to send a sample delivery: 
curl -X POST https://sandbox.api.openfx.com/v1/webhooks/subscriptions/wsub_01953e1a5f4b700a/test \
  -H "Authorization: Bearer sk_sandbox_your_api_key" \
  -H "X-Signature: <computed-signature>" \
  -H "X-Timestamp: 1740500000" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440024"
The test endpoint sends a real webhook delivery to your URL, signed with your subscription’s secret. Use this to verify:
  • Your endpoint is reachable from OpenFX’s infrastructure
  • Your signature verification works correctly
  • Your endpoint returns a 2xx status code

​
Multiple subscriptions

You can create multiple webhook subscriptions to route different event types to different endpoints. For example:
  • Payments endpoint — Receives payment.* events and routes to your payment processing service.
  • Onboarding endpoint — Receives customer.* events and routes to your onboarding service.
  • Audit endpoint — Receives ["*"] and routes to your logging/audit service.
Each subscription has its own signing secret, status, and delivery history.

​
Next steps

Signature Verification

Implement HMAC-SHA256 verification to secure your webhook endpoint.

Event Types

Browse all event types and their payload structures.

Secret Rotation

Rotate your webhook signing secret with zero downtime.