Custom Webhooks¶

Custom webhooks allow your systems to send events into Dxtra for privacy processing. When something happens in your application (a customer signs up, updates preferences, requests data deletion), you send an HTTP POST to Dxtra's webhook endpoint, and the event flows through the standard PII extraction and compliance pipeline.

How it works¶

Your System              Dxtra (Conduit)
     │                        │
     │  POST with event data  │
     ├────────────────────────►
     │  (Bearer + secret auth) │
     │                        ├─► PII extraction pipeline
     │  200 OK                ├─► Data subject resolution
     │ ◄────────────────────────├─► Data processing activity log
     │                        │

1. You configure a custom integration in the Dxtra dashboard, defining your processor's events and field mappings
2. Dxtra generates a webhook URL containing your data controller DID and data processor ID, plus auth credentials for use in request headers
3. Your system sends HTTP POST requests to that URL with event data
4. Dxtra validates the payload against your configured field mappings, extracts PII, and resolves or creates data subject records
5. A data processing activity is logged for compliance audit

Webhook URL format¶

Custom integration webhook URLs follow this pattern:

https://conduit.dxtra.ai/api/v1/integrations/custom/event?did={data_controller_did}&dpid={data_processor_id}

The URL contains two query parameters: did (your data controller DID) and dpid (your data processor ID).

Requests require two authentication headers:

• Authorization: Bearer <api_key> — Your API key (a Personal Access Token). The webhookAuth field returned when you create the integration contains this value with the Bearer prefix already included.
• x-webhook-secret: <webhook_secret> — Your data controller's webhook secret. This is the raw secret value (without the Bearer prefix).

Setting up a custom webhook integration¶

Step 1: Create the integration¶

In the Dxtra dashboard, navigate to Integrations and create a new Custom integration. Configure:

• Integration name — A descriptive name for this data source
• Payload structure — Define the expected fields and their mapping to Dxtra's data model

Step 2: Get the webhook URL and credentials¶

After creating the integration, Dxtra generates a webhook URL, an API key (for the Authorization header), and a webhook secret (for the x-webhook-secret header). Copy these values — you will configure your system to send events using them.

Step 3: Configure your system¶

Set up your application to send HTTP POST requests to the webhook URL when relevant events occur:

curl -X POST \
  "https://conduit.dxtra.ai/api/v1/integrations/custom/event?did={data_controller_did}&dpid={data_processor_id}" \
  -H "Authorization: Bearer {api_key}" \
  -H "x-webhook-secret: {webhook_secret}" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "account_created",
    "triggeredAt": "2026-04-06T10:30:00Z",
    "email": "customer@example.com"
  }'

The event and triggeredAt fields are always required. Additional fields (like email above) must match the field names you configured in Step 1. Only fields defined in your event configuration are validated and processed — any extra fields in the payload are ignored.

Step 4: Verify¶

Send a test event and check the Dxtra dashboard to confirm it was received and processed correctly.

Managing custom integrations¶

Custom integrations support full CRUD operations through the dashboard:

• Onboard — Create a new custom integration with payload mapping
• List — View all configured custom integrations
• Get — View details for a specific integration
• Update — Modify payload mapping or configuration
• Delete — Remove an integration and its webhook URL

Processing pipeline¶

Events received through custom webhooks are processed through Dxtra's data processing pipeline:

1. Validates the payload against the field mapping you configured during setup
2. Extracts PII fields (email, name, phone, etc.) based on your field-to-PII-taxonomy mappings
3. Resolves existing data subjects or creates new ones using privacy-preserving hashed links
4. Records a data processing activity linking the event to the data subject, processor, and event type

Error handling¶

The webhook endpoint returns the following responses:

Best practices¶

1. Use HTTPS — The webhook URL uses HTTPS by default; ensure your system sends over TLS
2. Include timestamps — Always include a triggeredAt timestamp so Dxtra can order events correctly
3. Avoid duplicate sends — Dxtra deduplicates events based on the combination of data controller, event type, processor, and PII field values within a short time window. Sending the exact same event twice in quick succession will result in the duplicate being skipped
4. Log webhook calls — Keep a log of sent webhooks on your side for debugging
5. Monitor delivery — Set up alerting for failed webhook deliveries (non-200 responses)

Troubleshooting¶

Events not appearing in Dxtra — Verify the webhook URL is correct and the token has not been regenerated. Check that your payload matches the configured field mapping. Inspect your HTTP response for error details.

Authentication errors — If you receive 401 responses, verify both the Authorization header (must include Bearer prefix with your API key) and the x-webhook-secret header (must be the raw webhook secret without a Bearer prefix). Both headers are required.

Payload mapping issues — If events are received but data is not extracted correctly, review the field mapping configuration in the dashboard. Ensure your payload field names match what Dxtra expects.

Related¶

• Custom integrations overview — Overview of custom integration options
• Consent management — Configure consent categories
• Data subject rights — Handle access and deletion requests