Webhooks

Webhooks deliver real-time HTTP POST notifications to your server when events occur on your Merx account. No polling required.

Available Events

Event	Trigger
order.filled	An energy order has been fully filled by providers
order.failed	An order could not be fulfilled
deposit.received	A TRX deposit has been confirmed on-chain
withdrawal.completed	A withdrawal has been broadcast and confirmed

See the events reference for full payload examples of each event type.

Payload Format

Every webhook delivery is an HTTP POST with a JSON body containing the event type, the event data, and a Unix timestamp.

200Webhook payload structure

{
  "event": "order.filled",
  "data": {
    "id": "ord_abc123",
    "status": "FILLED",
    "amount": 65000,
    "total_cost_sun": "5460000"
  },
  "timestamp": 1711200000
}

Signature Verification

Every delivery includes an X-Merx-Signature header containing an HMAC-SHA256 signature of the request body using your webhook secret. The header value is formatted as sha256=<hex_digest>. Always verify the signature before processing the payload.

See the verification guide for implementation details and code examples.

Retry Policy

If your endpoint returns a non-2xx status or fails to respond within 5 seconds, Merx retries the delivery up to 3 times with exponential backoff.

Attempt	Delay
1st retry	1 second
2nd retry	4 seconds
3rd retry	16 seconds

Auto-Deactivation

After 3 consecutive delivery failures (across any events), the webhook endpoint is automatically deactivated. You will need to re-enable it from the dashboard after fixing the issue.

WARNING

Your endpoint must respond within 5 seconds. Move any heavy processing to a background job and return 200 immediately.

Best Practices

Always verify the X-Merx-Signature header before processing
Return 200 quickly and process events asynchronously
Handle duplicate deliveries idempotently using the event data
Use HTTPS endpoints only
Monitor your endpoint for failures in the dashboard