Webhook Events

Mesta sends webhook notifications when key events occur in the system. Use webhooks to receive real-time updates about orders, senders, UBOs, beneficiaries, and deposits.

Setup

Register a webhook using the Create Webhook API, passing the event names you want to subscribe to
Verify signatures using your webhook signature key (see Webhook Signature Verification)
Return 2xx promptly to acknowledge receipt

You can register up to 5 webhooks.

Event Names

Event names use the form <entity>:<action> — note the colon, not a dot. Anything outside the
live tables in this section is rejected with a 400 VALIDATION_FAILED when you register the
webhook, including everything under Planned Events.

The <entity>:* wildcards subscribe to every event in that family, including events added later.

Order Events

Event	Description
`order:*`	All order events
`order:created`	Order has been accepted and persisted
`order:awaiting_funds`	Order is ready to receive funds
`order:awaiting_funds_timeout`	Funds were not received in time
`order:funds_received`	Funds have been received and confirmed
`order:in_progress`	Order is being processed
`order:sent_to_beneficiary`	Funds have been sent to the beneficiary
`order:success`	Order completed successfully
`order:failed`	Order failed
`order:cancelled`	Order was cancelled
`order:returned`	Payment was returned by the beneficiary bank
`order:proof_of_payment_received`	Proof of payment has been received for the order
`order:invoice_review_required`	The order's invoice requires review

Sender Events

Event	Description
`sender:*`	All sender events
`sender:created`	Sender has been created
`sender:kyb_pending`	Business sender verification is in progress
`sender:kyb_approved`	Business sender has been verified and approved
`sender:kyb_declined`	Business sender verification was declined
`sender:kyc_pending`	Individual sender verification is in progress
`sender:kyc_approved`	Individual sender has been verified and approved
`sender:kyc_declined`	Individual sender verification was declined
`sender:tos_link_generated`	A terms-of-service acceptance link has been generated
`sender:tos_accepted`	The sender accepted the terms of service
`sender:activated`	Sender is active and can transact
`sender:deactivated`	Sender has been deactivated

UBO Events

Event	Description
`ubo:*`	All UBO events
`ubo:created`	UBO has been created
`ubo:verification_pending`	UBO verification is in progress
`ubo:verification_approved`	UBO has been verified and approved
`ubo:verification_declined`	UBO verification was declined

Beneficiary Events

Event	Description
`beneficiary:*`	All beneficiary events
`beneficiary:created`	Beneficiary has been created
`beneficiary:verification_approved`	Beneficiary has been verified and approved
`beneficiary:verification_declined`	Beneficiary verification was declined

Deposit Events

Event	Description
`fiat_deposit:settled`	A fiat deposit has settled
`stablecoin_deposit:settled`	A stablecoin deposit has settled
`stablecoin_deposit:rejected`	A stablecoin deposit was rejected

Planned Events

🚧
Not available yet
The events below are reserved for future releases. They are not emitted today, and passing any of them to POST /v1/webhooks is rejected with 400 VALIDATION_FAILED. Do not build against them yet — subscribe to the live events above.

Planned event	Notes
`order:need_review`	`need_review` already exists as an order status; no event is emitted for it yet
`order:refund_in_progress`	Refunds are tracked today via the `refund_in_progress` order status
`order:refunded`	Refunds are tracked today via the `refunded` order status
`sender:verification_pending`	Use the live `sender:kyb_pending` / `sender:kyc_pending` events instead
`sender:verification_approved`	Use the live `sender:kyb_approved` / `sender:kyc_approved` events instead
`sender:verification_declined`	Use the live `sender:kyb_declined` / `sender:kyc_declined` events instead
`beneficiary:verification_pending`	—
`payment_method:approved`	`approved` already exists as a payment method status
`payment_method:declined`	`declined` already exists as a payment method status
`payment_method:pending_user_consent`	`pending_user_consent` already exists as a payment method status

Webhook Payload Format

Every webhook uses the same envelope. Only entity.data changes from event to event:

{
  "id": "00000000-0000-4000-b000-000000000000",
  "event": "order:success",
  "entity": {
    "id": "00000000-0000-4000-a000-000000000006",
    "type": "order",
    "data": {}
  }
}

Field	Type	Description
`id`	string	Unique event ID. Stable across replays — use it as your idempotency key.
`event`	string	Event name, in `<entity>:<action>` form (see tables above)
`entity.id`	string	ID of the object the event is about
`entity.type`	string	One of `order`, `sender`, `ubo`, `beneficiary`, `fiat_deposit`, `stablecoin_deposit`
`entity.data`	object	A snapshot of that object at the time the event fired

For a per-event breakdown of entity.data, see Sample Webhook payloads.

📘
Fields are omitted, not nulled, when they do not apply
Optional relations and scope-restricted fields may be absent from entity.data entirely. Read defensively rather than asserting on an exact key set.

Delivery and Retries

Each request carries a Content-Type: application/json header and an X-Webhook-Signature
header — a lowercase hex HMAC-SHA256 of the raw request body, signed with your webhook signature key.

If your endpoint does not return a 2xx response, Mesta retries delivery up to 5 attempts in
total, after which the event is moved to a dead-letter queue and is no longer retried
automatically.

Best Practices

Respond quickly — acknowledge with a 2xx as soon as you have persisted the event, and process it asynchronously.
Handle duplicates — use the event id to deduplicate. The same event may be delivered more than once.
Verify signatures — always verify X-Webhook-Signature before processing.
Handle unknown events — ignore event names you don't recognize. New events may be added.
Subscribe with wildcards — use order:*, sender:*, ubo:* or beneficiary:* if you want every event in a family, including ones added later.