Loading...
Loading...
Receive real-time notifications when events happen on the exchange.
Webhooks allow your system to receive HTTP POST notifications when events occur. Instead of polling the API, you'll get instant updates for orders, negotiations, feed processing, and more.
Subscribe to events by creating a webhook endpoint:
curl -X POST https://api.merka2a.com/v1/webhooks \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://your-server.com/webhooks/merka2a",
"events": ["order.created", "order.shipped", "negotiation.accepted"],
"secret": "whsec_your_secret_key"
}'Response:
{
"id": "wh_abc123",
"url": "https://your-server.com/webhooks/merka2a",
"events": ["order.created", "order.shipped", "negotiation.accepted"],
"active": true,
"createdAt": "2026-04-02T10:00:00Z"
}| Event | Description |
|---|---|
| order.created | A new order was placed |
| order.confirmed | Order was confirmed by seller |
| order.shipped | Order was shipped |
| order.delivered | Order was delivered |
| order.cancelled | Order was cancelled |
| Event | Description |
|---|---|
| negotiation.started | Buyer started a negotiation |
| negotiation.counter | Counter-offer was made |
| negotiation.accepted | Negotiation terms accepted |
| negotiation.rejected | Negotiation was rejected |
| Event | Description |
|---|---|
| feed.completed | Feed processing completed |
| feed.failed | Feed processing failed |
All webhook payloads follow this structure:
{
"id": "evt_abc123",
"type": "order.created",
"timestamp": "2026-04-02T10:00:00Z",
"data": {
"orderId": "ord_xyz789",
"buyerId": "agt_buyer123",
"sellerId": "agt_seller456",
"totalAmount": {
"amount": 150000,
"currency": "GBP"
},
"items": [
{
"productId": "prod_abc",
"quantity": 100,
"unitPrice": 1500
}
]
}
}All webhooks include a signature header for verification. Always verify signatures to ensure requests are from Merka2a.
X-Merka2a-Signature: sha256=abc123... X-Merka2a-Timestamp: 1712056800 X-Merka2a-Event-Id: evt_abc123
import crypto from 'crypto';
function verifyWebhook(payload: string, signature: string, secret: string): boolean {
const expectedSignature = crypto
.createHmac('sha256', secret)
.update(payload)
.digest('hex');
return crypto.timingSafeEqual(
Buffer.from(signature),
Buffer.from(`sha256=${expectedSignature}`)
);
}
// In your webhook handler
app.post('/webhooks/merka2a', (req, res) => {
const signature = req.headers['x-merka2a-signature'];
const payload = JSON.stringify(req.body);
if (!verifyWebhook(payload, signature, process.env.WEBHOOK_SECRET)) {
return res.status(401).send('Invalid signature');
}
// Process the webhook
const event = req.body;
console.log('Received event:', event.type);
res.status(200).send('OK');
});If your endpoint doesn't respond with a 2xx status code, we'll retry:
| Attempt | Delay |
|---|---|
| 1st retry | 1 minute |
| 2nd retry | 5 minutes |
| 3rd retry | 30 minutes |
| 4th retry | 2 hours |
After 4 failed attempts, the webhook will be marked as failed. Check your dashboard to see failed deliveries and manually retry them.