Webhooks

Webhooks provide a simple way for our platform to notify your application about events in real time. Instead of polling the API, you can register a callback URL that will receive an HTTP POST request whenever a specified event occurs.

1. Register a Webhook

Use the POST /webhooks endpoint to create a new webhook.

{
  "url": "https://example.com/webhook-receiver",
  "events": ["order.created", "order.updated"]
}

2. Verify the Endpoint

After registration, our system will send a challenge request to the URL. Respond with the exact challenge payload to confirm ownership.

{
  "type": "challenge",
  "challenge": "random-string-12345"
}

3. Security considerations

• Validate the Signature header (HMAC SHA256) using your secret.
• Use HTTPS for all webhook URLs.
• Implement retry logic – we retry up to 5 times with exponential backoff.

// Example Node.js verification
const crypto = require('crypto');
function verifySignature(req, secret) {
  const signature = req.headers['signature'];
  const payload = JSON.stringify(req.body);
  const expected = crypto.createHmac('sha256', secret).update(payload).digest('hex');
  return signature === expected;
}

4. Available Events

5. Testing Webhooks

Use our sandbox environment or the Webhook Tester to simulate events.

6. Troubleshooting

• 404 Not Found: Verify the URL is reachable.
• 401 Unauthorized: Check your secret and signature validation.
• 500 Server Error: Ensure your endpoint returns a 2xx status within 5 seconds.