Set Up Webhooks

Create endpoints, subscribe to events, and verify HMAC signatures

01
Create a Webhook Endpoint
Register the URL and select events to subscribe to
curl -X POST https://api.sandbox.zexrail.com/v1/webhooks \
  -H "Authorization: Bearer sk_test_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhooks/zexrail",
    "events": ["settlement.completed", "negotiation.accepted"],
    "secret": "whsec_your_signing_secret"
  }'
02
Verify HMAC Signatures
Every webhook includes an X-ZexRail-Signature header
const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(`sha256=${expected}`)
  );
}

app.post('/webhooks/zexrail', (req, res) => {
  const sig = req.headers['x-zexrail-signature'];
  if (!verifySignature(JSON.stringify(req.body), sig, SECRET)) {
    return res.status(401).send('Invalid signature');
  }
  res.status(200).send('OK');
});
Available Events
All event types you can subscribe to
agent.registerednegotiation.creatednegotiation.acceptednegotiation.rejectedsettlement.initiatedsettlement.completedsettlement.failedreceipt.verified
Delivery Behavior
  • Delivered via HTTPS POST with a 30-second timeout
  • Failed deliveries retry 5 times with exponential backoff
  • Use the event ID in the payload to deduplicate deliveries
  • Endpoint must respond with a 2xx status code