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  │
     ├────────────────────────►
     │  (encrypted token auth) │
     │                        ├─► PII extraction pipeline
     │                        ├─► Compliance processing
     │  200 OK                ├─► Audit trail
     │ ◄────────────────────────
     │                        │

1. You configure a custom integration in the Dxtra dashboard
2. Dxtra generates a webhook URL containing your data controller DID and data processor ID, plus separate API credentials (API key and webhook secret) for use in request headers.
3. Your system sends HTTP POST requests to that URL with event data
4. Dxtra processes the payload through its PII extraction pipeline
5. Events are logged in the compliance audit trail

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 must include Authorization: Bearer <webhook_auth> and x-webhook-secret: <webhook_auth> headers, where the credential value is the webhookAuth field returned when you create the integration.

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¶

After creating the integration, Dxtra generates a webhook URL with an encrypted token. Copy this URL — you will configure your system to send events to it.

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 {webhook_auth}" \
  -H "x-webhook-secret: {webhook_auth}" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "account_created",
    "triggeredAt": "2026-04-06T10:30:00Z",
    "email": "customer@example.com",
    "metadata": {
      "source": "signup_form",
      "ip_country": "DE"
    }
  }'

The payload structure is flexible and configured through the dashboard. Dxtra maps your fields to its internal data model based on the configuration you set up in Step 1.

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

PII extraction pipeline¶

Events received through custom webhooks are processed through Dxtra's standard PII extraction pipeline. The pipeline:

1. Parses the incoming payload based on your configured field mapping
2. Identifies and extracts PII fields (email, name, phone, etc.)
3. Creates or updates data subject records
4. Logs the processing activity for compliance audit

Error handling¶

Your webhook endpoint should expect the following responses:

For failed requests, implement retry logic with exponential backoff in your sending system.

Best practices¶

1. Use HTTPS — The webhook URL uses HTTPS by default; ensure your system sends over TLS
2. Include timestamps — Always include an event timestamp so Dxtra can order events correctly
3. Be idempotent — If you retry a failed request, include a unique event ID so Dxtra can deduplicate
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

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, your API key or webhook secret may be invalid. Check your API key and webhook secret credentials in the dashboard.

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