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.
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
These events track the lifecycle of an order from creation to completion.
Event Description order.createdOrder has been created order.awaiting_fundsOrder is ready to receive funds order.awaiting_funds_timeoutFunds were not received in time order.funds_receivedFunds have been received and confirmed order.in_progressOrder is being processed order.need_reviewOrder requires manual review order.sent_to_beneficiaryFunds have been sent to the beneficiary order.successOrder completed successfully order.failedOrder failed order.cancelledOrder was cancelled order.refund_in_progressRefund is being processed order.refundedRefund has been completed
Event Description sender.verification.pendingSender verification is in progress sender.verification.approvedSender has been verified and approved sender.verification.declinedSender verification was declined
Event Description beneficiary.verification.pendingBeneficiary verification is in progress beneficiary.verification.approvedBeneficiary has been verified and approved beneficiary.verification.declinedBeneficiary verification was declined
Event Description payment_method.approvedPayment method has been approved payment_method.declinedPayment method was declined payment_method.pending_user_consentPayment method requires user consent
All webhook payloads follow this structure:
JSON
{
"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 idstring Unique event ID typestring Event type (see tables above) merchantIdstring Your merchant ID dataobject Event-specific payload containing the affected entity createdAtstring ISO 8601 timestamp
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. 