Webhook Overview

Events

MexicoP2P sends webhook notifications for order lifecycle events. Configure your webhook URL in the Partner Dashboard.

Event	When
`order.created`	Order placed, entering `PENDING_DEPOSIT`
`order.deposit_confirmed`	Escrow deposit confirmed on Starknet
`order.locked`	Buyer locked the order
`order.payment_verified`	SPEI payment (CEP) validated
`order.completed`	Escrow released, trade finished
`order.refunded`	Crypto refunded to seller
`order.lock_expired`	Buyer didn't complete payment in time
`order.disputed`	Dispute opened by either party
`order.dispute_resolved`	Dispute resolved by admin

Payload format

All webhook payloads follow the same structure:

{
  "event": "order.completed",
  "timestamp": "2025-06-15T12:35:00.000Z",
  "data": {
    "orderId": "ord_xyz789",
    "escrowOrderId": "0x1a2b3c...",
    "status": "COMPLETED",
    "partnerUserRef": "user_12345",
    "token": "USDC",
    "amount": 100,
    "totalMxn": 1725.00,
    "exchangeRate": 17.25,
    "buyerWallet": "0x04a1b2c3...",
    "lockedAt": "2025-06-15T12:15:00.000Z",
    "completedAt": "2025-06-15T12:35:00.000Z",
    "createdAt": "2025-06-15T12:03:00.000Z"
  }
}

Payload fields

Field	Type	Description
`event`	string	Event type
`timestamp`	string	When the event occurred
`data.orderId`	string	Order ID
`data.escrowOrderId`	string	Starknet escrow order ID
`data.status`	string	Current order status
`data.partnerUserRef`	string	Your user reference
`data.token`	string	`USDC` or `USDT`
`data.amount`	number	Token amount
`data.totalMxn`	number	Total MXN value
`data.exchangeRate`	number	USD/MXN rate
`data.buyerWallet`	string\|null	Buyer's Starknet wallet
`data.lockedAt`	string\|null	When buyer locked
`data.completedAt`	string\|null	When trade completed
`data.createdAt`	string	Order creation time

Headers

Each webhook delivery includes these headers:

Header	Description
`X-Webhook-Id`	Unique delivery ID
`X-Webhook-Signature`	HMAC-SHA256 hex signature
`X-Webhook-Timestamp`	Unix timestamp (seconds)
`Content-Type`	`application/json`

Delivery

Timeout: 10 seconds per attempt
Success: Any 2xx HTTP response
Failure: Non-2xx response or timeout

Retry policy

Failed deliveries are retried with exponential backoff:

Attempt	Delay after failure
1st retry	30 seconds
2nd retry	2 minutes
3rd retry	10 minutes
4th retry	30 minutes
5th retry	2 hours

After 5 failed attempts, the delivery is marked as FAILED. Check failed deliveries via GET /webhooks?status=FAILED.

Best practices

Return 200 OK quickly — process the webhook payload asynchronously
Use the X-Webhook-Id for idempotency (you may receive the same event twice)
Verify the signature before processing (see Signature Verification)
Store the raw payload for debugging