Skip to main content

Webhooks Overview

When an event occurs (such as an order status change, filings error or document status change), we'll send a HTTP POST request to the URL you've configured. This allows your application to react immediately to important events without the need for constant API polling.

Getting Started​

Prerequisites​

Before setting up webhooks, ensure that:

  • Your account has webhook functionality enabled (contact our support team if needed)
  • You have a publicly accessible HTTPS endpoint ready to receive webhook events
  • Your endpoint can respond with a 200 OK status code within 5 seconds

Enabling Webhooks​

To enable webhooks for your account:

  1. Contact Support: Reach out to our support team to enable webhook functionality for your account
  2. Provide Endpoint Details: Share your webhook endpoint URL
  3. Configure Events: Specify which events you want to receive notifications for
  4. Test Integration: We'll help you test the webhook delivery to ensure everything works correctly

Webhook Configuration​

Endpoint Requirements​

  • Protocol: Only HTTPS endpoints are supported for security
  • Response Time: Your endpoint must respond within 10 seconds
  • Response Code: Return a 200 OK status code to acknowledge receipt
  • Content Handling: Be prepared to handle JSON payloads

Request Format​

All webhook requests are sent with:

  • Method: POST
  • Content-Type: application/json
  • Headers: Standard HTTP headers plus an optional Authorization header that you can use to authenticate the request.

Payload Structure​

Each webhook payload includes:

{
  "event_id": "1234567890",
  "event": {
      "name": "order_status_change",
      "changed_field": "status",
      "old_status": "Active",
      "new_status": "Cancelled"
  },
  "data": {
    // Event-specific data
    "order": {
      ...
    }
  }
}

Retries​

If your webhook endpoint is unreachable, we'll retry delivering the webhook 3 times (by default) after first request in the following times: 1, 2 and 4 minutes. If we don't receive a 200 OK status code, we'll stop retrying and mark the webhook as failed. If the webhook is successfully delivered, we'll mark it as delivered.

Event Types​

Common webhook events include:

  • Order Status Updates: When order status changes

Check the Webhooks List for a complete list of available events and their payload structures.

Best Practices​

Handling Webhooks​

  1. Idempotency: Use the event_id to ensure you process each event only once
  2. Quick Response: Acknowledge receipt quickly and process events asynchronously
  3. Error Handling: Implement proper error handling and logging
  4. Validation: Verify webhook authenticity using provided signatures and optional Authorization header (bearer token)

Endpoint Implementation​

// Example webhook endpoint
app.post('/webhooks', (req, res) => {
  const { event_type, event_id, data } = req.body;
  
  // Acknowledge receipt immediately
  res.status(200).send('OK');

  // if token is setup in the header, verify it. Token should be parsed as Bearer token.
  if (req.headers['authorization']) {
    const token = req.headers['authorization'].split(' ')[1];
    if (token !== process.env.WEBHOOK_TOKEN) {
      console.log('Invalid webhook token');
      return res.status(401).send('Unauthorized');
    }
  }

  // Verify webhook signature
  const payload = req.body;
  const secret = process.env.WEBHOOK_SECRET;
  const signature = req.headers['x-webhook-signature'];

  if (!verifyWebhookSignature(payload, signature, secret)) {
    console.log('Invalid webhook signature');
    return;
  }
  
  // Process event asynchronously
  processWebhookEvent(event_type, event_id, data);
});

Security Considerations​

Network Security​

  • HTTPS Only: All webhook endpoints must use HTTPS encryption
  • IP Allowlisting: Consider restricting access to our webhook IP ranges
  • Firewall Configuration: Ensure your firewall allows incoming connections from our servers

Data Protection​

  • Signature Verification: Implement webhook signature verification to ensure authenticity
  • Rate Limiting: Implement appropriate rate limiting on your webhook endpoint
  • Data Validation: Always validate incoming webhook data before processing

Signature Validation​

All webhook requests include a signature header that you should validate to ensure the request is authentic and from our servers.

How It Works​

  1. Signature Generation: We generate an HMAC-SHA256 signature using your webhook secret key and the raw request body
  2. Header Inclusion: The signature is included in the X-Webhook-Signature header as sha256=<signature>
  3. Verification: Your endpoint should generate the same signature and compare it with the received one

Implementation​

Getting Your Secret Key Your webhook secret key is provided when webhooks are configured for your account. Contact support to obtain your secret key.

Signature Verification Example (Node.js)

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  // Extract the signature from the header (format: "sha256=<signature>")
  const receivedSignature = signature.replace('sha256=', '');
  
  // Generate the expected signature
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload, 'utf8')
    .digest('hex');
  
  // Use constant-time comparison to prevent timing attacks
  return crypto.timingSafeEqual(
    Buffer.from(receivedSignature, 'hex'),
    Buffer.from(expectedSignature, 'hex')
  );
}

Important Notes

  • Always use the raw request body (before JSON parsing) for signature verification
  • Use constant-time comparison functions to prevent timing attacks
  • Store your webhook secret securely (environment variables, secrets manager, etc.)
  • Validate the signature before processing any webhook data

Monitoring​

  • Response Monitoring: We monitor webhook delivery success rates
  • Automatic Disabling: Webhooks may be automatically disabled if:
    • Your endpoint consistently returns non-200 status codes
    • Your endpoint times out frequently
    • Your endpoint is unreachable for an extended period

Troubleshooting​

Common Issues​

  1. Webhooks Not Received

    • Verify your endpoint is publicly accessible
    • Check firewall and security group settings
    • Ensure you're returning a 200 status code

  2. Duplicate Events

    • Implement idempotency using event_id
    • Check for multiple webhook configurations

  3. Webhook Disabled

    • Check with support if webhooks were disabled due to delivery failures
    • Review endpoint logs for errors

  4. Unauthorized or invalid token

    • Check if the Authorization header is set and the token is correct
    • Check if the token is set in the environment variables
    • Check if the token is set in the header
    • Check if the token is set in the request body
    • Check if the token is valid

  5. Invalid Signature

    • Check if the signature is set in the header
    • Check if the signature is set in the request body
    • Check if the signature is correct
    • Check if the signature is valid

Testing Your Integration​

You can test your webhook endpoint by:

  1. Setting up a test endpoint using tools like ngrok for local development
  2. Requesting test events from our support team
  3. Monitoring webhook delivery in your application logs

Support​

If you need assistance with webhook setup or troubleshooting:

  • Contact our support team for account-level webhook configuration
  • Refer to our API documentation for technical implementation details
  • Monitor your webhook endpoint logs for delivery and processing issues

For immediate assistance, please contact our support team with your account details and webhook configuration requirements.