Skip to main content
POST
Create a webhook subscription

What this endpoint does

Registers an HTTPS endpoint to receive signed Wayex events for this tenant account.

When to use it

Create one when your integration needs asynchronous transfer, Treasury, verification, or route updates.

Before you call

Use a secret API key with webhook write access. The destination must be an HTTPS endpoint that can preserve the raw request body and store the signing secret securely.

Money and balance effect

This changes a resource or configuration but does not directly reserve, debit, credit, or settle wallet money.

States and completion

Creation confirms the subscription exists; it does not prove your endpoint acknowledged a delivery. Inspect delivery records and verify every signature.

Safe retries

Send a unique Idempotency-Key for the logical action. If the response is lost, retry the same payload with the same key; never create a new key merely because the first response timed out. Read Webhooks for the complete workflow.

Authorizations

Authorization
string
header
required

Send the same Wayex API key as Authorization: Bearer <key>.

Headers

Idempotency-Key
string
required

A unique key for this logical action. Reuse the same key and identical payload when retrying after an unknown response.

Required string length: 8 - 255

Body

application/json
url
string<uri>
required

The HTTPS endpoint Wayex POSTs signed event deliveries to. Must be https and must resolve to a public address — private, loopback, link-local and metadata destinations are refused.

eventTypes
enum<string>[]
required

The event types this subscription receives.

Minimum array length: 1
Available options:
counterparty.created,
counterparty.invited,
counterparty.activated,
customer.created,
kyc.updated,
payment_route.created,
payment_route.activity.created,
rate.updated,
quote.created,
transfer.created,
transfer.updated,
transfer.completed,
treasury.wallet.updated,
treasury.payin.updated,
treasury.deposit.updated,
treasury.payout.updated,
treasury.withdrawal.updated,
treasury.conversion.updated,
approval.created,
approval.resolved
secret
string
required

The HMAC signing secret; stored encrypted and never returned in any response.

Minimum string length: 8

Response

The created subscription (the signing secret is never echoed).

A webhook subscription (the signing secret is never echoed).

id
string
required

The subscription id.

url
string<uri>
required

The endpoint deliveries are sent to.

eventTypes
enum<string>[]
required

The event types subscribed to.

Available options:
counterparty.created,
counterparty.invited,
counterparty.activated,
customer.created,
kyc.updated,
payment_route.created,
payment_route.activity.created,
rate.updated,
quote.created,
transfer.created,
transfer.updated,
transfer.completed,
treasury.wallet.updated,
treasury.payin.updated,
treasury.deposit.updated,
treasury.payout.updated,
treasury.withdrawal.updated,
treasury.conversion.updated,
approval.created,
approval.resolved
status
enum<string>
required

Whether the subscription receives events.

Available options:
active,
disabled
createdAt
string
required

When the subscription was created (ISO 8601).