Webhook Events

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

Setup

Register a webhook using the Create Webhook API
Verify signatures using the shared secret (see Webhook Signature Verification)
Return 200 OK promptly to acknowledge receipt

Event Types

Order Events

These events track the lifecycle of an order from creation to completion.

Event	Description
`order.created`	Order has been created
`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.need_review`	Order requires manual review
`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.refund_in_progress`	Refund is being processed
`order.refunded`	Refund has been completed

Sender Events

Event	Description
`sender.verification.pending`	Sender verification is in progress
`sender.verification.approved`	Sender has been verified and approved
`sender.verification.declined`	Sender verification was declined

Beneficiary Events

Event	Description
`beneficiary.verification.pending`	Beneficiary verification is in progress
`beneficiary.verification.approved`	Beneficiary has been verified and approved
`beneficiary.verification.declined`	Beneficiary verification was declined

Payment Method Events

Event	Description
`payment_method.approved`	Payment method has been approved
`payment_method.declined`	Payment method was declined
`payment_method.pending_user_consent`	Payment method requires user consent

Webhook Payload Format

All webhook payloads follow this structure:

{
  "id": "evt_550e8400-e29b-41d4-a716-446655440000",
  "type": "order.success",
  "merchantId": "550e8400-e29b-41d4-a716-446655440001",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440002",
    "status": "COMPLETED",
    "senderId": "550e8400-e29b-41d4-a716-446655440003",
    "beneficiaryId": "550e8400-e29b-41d4-a716-446655440004"
  },
  "createdAt": "2025-01-15T10:30:00.000Z"
}

Field	Type	Description
`id`	string	Unique event ID
`type`	string	Event type (see tables above)
`merchantId`	string	Your merchant ID
`data`	object	Event-specific payload containing the affected entity
`createdAt`	string	ISO 8601 timestamp

Best Practices

Respond quickly — Return 200 within 5 seconds. Process webhooks asynchronously.
Handle duplicates — Use the event id to deduplicate. The same event may be delivered more than once.
Verify signatures — Always verify the webhook signature before processing.
Handle unknown events — Ignore event types you don't recognize. New events may be added.
Implement retries — If your endpoint returns a non-2xx status, Mesta will retry delivery with exponential backoff.