Webhooks Integration

Introduction to Webhooks

Webhooks are a powerful way to enable automated workflows and real-time data synchronization between different applications. Instead of constantly polling for updates, webhooks allow applications to "push" information to you automatically when specific events occur.

Our platform supports outgoing webhooks, which means we can send notifications to your specified URL whenever a significant event happens within your account. This is ideal for:

• Notifying your internal systems of new data.
• Triggering actions in other services based on events.
• Keeping your dashboards and analytics up-to-date in real-time.

Setting Up Webhooks

To configure outgoing webhooks, navigate to your Account Settings -> Integrations -> Webhooks section in the dashboard.

1. Add New Webhook: Click the "Add Webhook" button.
2. Endpoint URL: Enter the URL where you want to receive webhook notifications. This URL must be publicly accessible and capable of handling POST requests.
3. Events: Select the specific events that should trigger a webhook. You can choose from a list of available events, such as 'new_order', 'user_updated', 'payment_received', etc.
4. Authentication (Optional): Configure any necessary authentication headers or methods if your endpoint requires them.
5. Save: Save your webhook configuration.

Once saved, the system will start sending events to your specified URL as they occur.

Receiving Webhooks

Your application's endpoint will receive HTTP POST requests from our platform. Each request will contain a JSON payload detailing the event that occurred.

Your server should be configured to:

• Accept POST requests at the specified endpoint URL.
• Parse the incoming JSON payload.
• Process the event data accordingly.
• Return an appropriate HTTP status code (e.g., 200 OK) to acknowledge receipt. Returning non-2xx status codes may result in retry attempts.

Payload Structure

The JSON payload sent with each webhook request provides detailed information about the event. The structure can vary slightly depending on the event type, but a common structure includes:

{
    "event_type": "new_order",
    "timestamp": "2023-10-27T10:30:00Z",
    "data": {
        "order_id": "ORD-123456789",
        "customer_id": "CUST-ABCDEF",
        "total_amount": 150.75,
        "currency": "USD",
        "items": [
            {
                "sku": "PROD-A1",
                "name": "Awesome Gadget",
                "quantity": 2,
                "price": 50.00
            },
            {
                "sku": "PROD-B2",
                "name": "Super Widget",
                "quantity": 1,
                "price": 50.75
            }
        ],
        "order_date": "2023-10-27T10:25:00Z",
        "status": "pending"
    },
    "created_at": "2023-10-27T10:30:00Z"
}

Key Fields:

• event_type: The type of event that occurred (e.g., "new_order").
• timestamp: The time the event was generated.
• data: An object containing the specific details of the event. This structure is event-dependent.
• created_at: When the webhook payload was created by our system.

Security Best Practices

Ensuring the security of your webhook endpoints is crucial. Here are some recommended practices:

const crypto = require('crypto');

const secret = 'YOUR_WEBHOOK_SECRET';
const signature = req.headers['x-webhook-signature'];
const payload = req.body; // Assuming body is already parsed as JSON

const hmac = crypto.createHmac('sha256', secret);
hmac.update(JSON.stringify(payload));
const computedSignature = hmac.digest('hex');

if (signature === computedSignature) {
    // Request is valid
    console.log('Webhook signature verified!');
} else {
    // Request is invalid
    console.error('Invalid webhook signature!');
    res.status(401).send('Unauthorized');
}

Other Security Considerations:

• HTTPS: Always use HTTPS for your webhook endpoint to encrypt data in transit.
• IP Whitelisting: If possible, configure your firewall to only accept requests from our known IP ranges. (Contact support for the current list of IP addresses).
• Input Validation: Treat all incoming data as untrusted and validate it thoroughly before processing.
• Rate Limiting: Implement rate limiting on your endpoint to prevent abuse.

Troubleshooting Common Issues

Encountering problems? Here are some common issues and how to resolve them:

Debugging Tips:

• Check Logs: Review both our platform's webhook delivery logs (if available in your dashboard) and your server's application logs.
• Test Endpoint: Use tools like curl or Postman to send test POST requests to your endpoint and verify it's accessible and functioning correctly.
• Payload Mismatch: Ensure you are correctly parsing the JSON payload and that your code handles the expected data structure for each event type.
• Secret Key: Double-check that your webhook secret is correctly configured on both ends and that the signature calculation is accurate.