Receiving Inbound Webhooks

This is only relevant if you are self-hosting Sombra and using our Preference Management product!

This guide explains how to set up a webhook receiver that securely forwards incoming requests to your locally hosted Sombra cluster instance. The receiver will transform incoming requests into a standardized PUT request to the /v1/preferences endpoint with proper authentication.

When you need to receive webhooks from external vendors and forward them to Sombra, you'll need to:

  1. Set up a webhook receiver endpoint that's accessible to external services
  2. Transform incoming requests into the expected Sombra format. The API is documented here.
  3. Add proper authentication headers
  4. Forward the request to your Sombra cluster

Here's a high-level example of how to implement this using Node.js and Express:

const express = require('express');
const axios = require('axios');
const app = express();

// Your Sombra configuration
const SOMBRA_URL = 'http://localhost:5040'; // Make sure this points to your internal sombra (customer-ingress)
const SOMBRA_INTERNAL_KEY = process.env.SOMBRA_INTERNAL_KEY;
const TRANSCEND_API_KEY = process.env.TRANSCEND_API_KEY;

app.put('/v1/preferences', express.json(), async (req, res) => {
  try {
    // You may wish to transform the payload before forwarding to Sombra,
    // But usually it is possible to setup the webhook in the external vendor
    // such that it conforms to our API format.
    await axios.put(`${SOMBRA_URL}/v1/preferences`, req.body, {
      headers: {
        Authorization: `Bearer ${TRANSCEND_API_KEY}`,
        'x-sombra-authorization': `Bearer ${SOMBRA_INTERNAL_KEY}`,
        'Content-Type': 'application/json',
      },
    });

    res.status(200).json({ success: true });
  } catch (error) {
    console.error('Error forwarding webhook:', error);
    res.status(500).json({ error: 'Failed to process webhook' });
  }
});

app.listen(3001, () => {
  console.log('Webhook receiver listening on port 3001');
});

  1. Authentication: Ensure your webhook receiver endpoint is secured with appropriate authentication mechanisms (e.g., API keys, HMAC signatures).

  2. Input Validation: Validate all incoming webhook data before forwarding to Sombra.

  3. Rate Limiting: Implement rate limiting to prevent abuse of your webhook endpoint.

  4. HTTPS: Always use HTTPS for your webhook receiver endpoint.

  5. Error Handling: Implement proper error handling and logging for failed webhook deliveries.

The following environment variables should be configured:

  • SOMBRA_URL: The URL of your local Sombra cluster. Make sure this is for your internal Sombra endpoint!
  • TRANSCEND_API_KEY: The Transcend API Key. You can create one by navigating to Admin Dashboard > Infrastructure. The API key needs the following scopes:
    • Modify User Stored Preferences
    • View Managed Consent Database Admin API
    • View Preference Store Settings
  • SOMBRA_INTERNAL_KEY: The Sombra API key. The hash of this key is stored in the INTERNAL_KEY_HASH environment variable.

To test your webhook receiver:

  1. Start your webhook receiver service
  2. Use a tool like cURL or Postman to send test webhooks to your endpoint
  3. Monitor the logs to ensure proper forwarding to Sombra
  4. Verify that the data appears correctly in your Sombra cluster

  1. Idempotency: Implement idempotency checks to handle duplicate webhook deliveries.

  2. Retries: Implement a retry mechanism for failed forwards to Sombra.

  3. Monitoring: Set up monitoring and alerting for your webhook receiver.

  4. Documentation: Document the expected webhook payload format and any specific requirements for your implementation.

  5. Versioning: Consider implementing versioning for your webhook endpoints to handle future changes gracefully.