Skip to main content

API Overview

Webhooks send us events from your backend, without browser dependencies. Ideal for e-commerce platforms, CRM systems, and any scenario where server-side tracking is required.

Looking for the other direction?

To receive every processed event in your own system, that is a destination, not an API: see Your Endpoint.

Prerequisites​

Plan Requirements

Webhook access is available with Data Source Addon on FLEX plan and above. Contact DATA Reshape team to enable access for your account.

Once approved, you'll receive:

  • Script ID — your unique project identifier (8 characters, uppercase alphanumeric)
  • Access Token — secret authentication key
  • Webhook Base URL — requests go to your own tracking subdomain, the same first-party host that serves the tracking script (e.g. https://dre2.YOUR_DOMAIN.TLD). Any other host is rejected.

Authentication​

All webhook requests require:

  • Method: POST
  • Content-Type: application/json
  • Header: X-Dre-Access-Token: YOUR_ACCESS_TOKEN
  • Query Parameter: id=YOUR_SCRIPT_ID

Integration Methods​

Standard Integration​

Universal endpoint for tracking any approved event using the Reshape Standard Syntax.

Event Create — single endpoint for all event types (checkout_completed, lead_created, order_canceled, etc.) with support for products, shipping, payments, coupons, user data, cookies, and consent.

$endpoint = 'https://dre2.YOUR_DOMAIN.TLD/webhooks/reshape/event?id=YOUR_SCRIPT_ID';

$ch = curl_init($endpoint);
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode($payload),
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'X-Dre-Access-Token: YOUR_ACCESS_TOKEN'
    ],
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 30
]);

$response = curl_exec($ch);
curl_close($ch);

Custom Integration​

CUSTOM Plan Exclusive

Available exclusively for CUSTOM plan subscribers with dedicated development resources.

About Custom Integration — specialized webhook endpoints designed for your specific business logic, data structures, and operational workflows. Built by the DATA Reshape team in collaboration with your technical team.

Testing​

Append /test to the endpoint path to validate a payload before going live:

POST https://dre2.YOUR_DOMAIN.TLD/webhooks/reshape/event/test?id=YOUR_SCRIPT_ID

The /test endpoint processes synchronously, does not send to any destination, and returns the full errors, warnings and data_received. Setting context.environment: "dev" in the body only skips destination delivery — it does not return this feedback.

Response Format​

Production (async)​

The production endpoint acknowledges immediately and processes in the background — no per-event feedback:

{
  "emitter": "DATA Reshape",
  "detail": "OK",
  "level": 2,
  "version": 6
}

Test — Success​

{
  "emitter": "DATA Reshape",
  "detail": "Received. This has been processed.",
  "level": 2,
  "version": 6,
  "errors": [],
  "warnings": [
    "context.url is missing. Fallback to config host.",
    "consent object does not match the required format and will be set to an object with all values set to true."
  ],
  "data_received": { }
}

Test — Validation Failure​

{
  "emitter": "DATA Reshape",
  "detail": "Processing failed — see errors.",
  "level": 2,
  "version": 6,
  "errors": [
    "event.id is missing or does not match the required format."
  ],
  "warnings": [],
  "data_received": { }
}

Getting Started​

  1. Get credentials — contact the DATA Reshape team for your Script ID and Access Token
  2. Review the data objects — see Objects Documentation for the complete reference
  3. Implement the endpoint — use Event Create for standard integration
  4. Test with /test — validate payloads against the /webhooks/reshape/event/test endpoint before going to production
  5. Go live — switch to the production /webhooks/reshape/event endpoint when ready

Support​