Webhooks¶

Dxtra receives webhook events from third-party platforms to track data processing activities, manage consent, and automate privacy compliance. When events occur in your connected platforms (e.g., a new customer in Stripe, an order in Shopify), those platforms send webhook notifications to Dxtra.

graph LR
    subgraph "Your Platforms"
        Stripe[Stripe]
        Shopify[Shopify]
        Mailchimp[Mailchimp]
        Others[Other Platforms]
    end

    subgraph "Dxtra"
        Conduit[Webhook Receiver]
        Validation[Signature Validation]
        Processing[Privacy Processing]
        DB[(Database)]
    end

    Stripe -->|Customer events| Conduit
    Shopify -->|Order events| Conduit
    Mailchimp -->|Subscriber events| Conduit
    Others -->|Events| Conduit

    Conduit --> Validation
    Validation --> Processing
    Processing --> DB

Webhook Endpoints¶

Integration webhooks use one of two URL patterns depending on the integration:

Legacy DID + DX Key integrations:

https://conduit.dxtra.ai/api/v1/integrations/{service}/event?did={YOUR_DID}&dxKey={YOUR_DX_KEY}

JWE token integrations (auto-configured during setup):

https://conduit.dxtra.ai/api/v1/integrations/{service}/event?token={ENCRYPTED_TOKEN}

You configure this URL in your third-party platform's webhook settings. When events occur, the platform sends HTTP POST requests to this endpoint.

Supported Integrations¶

The full base URL for all endpoints is https://conduit.dxtra.ai/api/v1.

Customer Data Redaction Endpoints¶

Some integrations provide compliance endpoints for processing data subject erasure requests:

Authentication¶

Webhooks are authenticated using one of these methods depending on the integration:

DID + DX Key¶

Most integrations authenticate via DID and DX Key as URL query parameters (?did={YOUR_DID}&dxKey={YOUR_DX_KEY}). Both parameters are validated on every incoming webhook request. Find your DID and DX Key in the dashboard under Developers.

Available Events¶

Event notifications are triggered by database changes. See the Events Reference for a complete list of available events.

Security Considerations¶

For Integration Webhooks¶

• DID and DX Key: Required query parameters authenticate the webhook source
• Signature Verification: Each integration uses service-specific signature verification (e.g., Shopify HMAC, Stripe signatures)
• Rate Limiting: Automatic protection against webhook abuse (1000 requests per 15 minutes)
• IP Allowlisting: Consider restricting webhook endpoints to known service IPs
• Input Validation: All webhook payloads validated with Zod schemas before processing
• Error Handling: Secure error responses that don't expose internal system information

For Event Notifications¶

• Internal Only: Hasura event triggers are internal to the Dxtra platform
• Authentication: Event processing happens within the secured internal network
• Audit Logging: All events are logged for compliance and debugging

Example Payload¶

Here is an example of the JSON payload that we would send for a data_subject_request.created event:

{
  "event": "data_subject_request.created",
  "data": {
    "id": "e5f6a7b8-c9d0-1234-5678-901234567890",
    "type": "access",
    "status": "pending",
    "data_subject_id": "f8e7d6c5-b4a3-2109-8765-432109876543"
  }
}

You find your DID and DX Key in the dashboard under Developers. These parameters are validated on every incoming webhook request.

JWE Token¶

Newer integrations (such as Shopify) use an encrypted JWE token:

?token={ENCRYPTED_TOKEN}

The token is generated automatically during integration setup and contains your DID and DX Key in encrypted form.

Platform Signature Verification¶

In addition to DID/DX Key authentication, Dxtra verifies the cryptographic signature of each webhook payload to confirm it was sent by the expected platform:

Payload Validation¶

All incoming webhook payloads are validated against a schema before processing. Invalid payloads are rejected with an error response.

What Happens When a Webhook Arrives¶

1. Authentication -- DID/DX Key or JWE token is validated
2. Signature verification -- Platform-specific cryptographic verification
3. Payload validation -- Schema validation of the request body
4. Data controller resolution -- Identifies your organization from the credentials
5. Event extraction -- Parses the platform-specific event data
6. PII extraction -- Identifies personal data fields in the payload
7. Privacy-preserving processing -- Hashes identifiers for privacy compliance
8. Record creation -- Creates processing activity records and updates data subject profiles

Setting Up Webhooks¶

Each integration has its own setup process. See the specific integration guide for step-by-step instructions:

• Shopify
• Stripe
• Mailchimp
• WooCommerce

For the full list of integrations, see Integrations Overview.

Error Handling¶

Most platforms automatically retry failed webhooks. Configure your platform's retry settings to allow for transient errors.

Related Pages¶

• Integrations Overview -- All supported platforms
• Actions Reference -- GraphQL mutations and queries
• Events Reference -- Internal event triggers
• Rate Limits -- Request throttling details