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.verifiedDelivery 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