Custom Webhook

When to Use a Custom Webhook

Custom webhooks let you forward scrubbed events to any system that accepts HTTP POST requests. Common use cases include:

• CRMs -- Send lead events to HubSpot, Salesforce, or Zoho via their webhook integrations.
• Custom backends -- Forward events to your own API for additional processing, storage, or enrichment.
• Data warehouses -- Pipe events into a collector like Segment, Snowplow, or an AWS Lambda function for ingestion.
• Notification systems -- Trigger alerts in Slack, Discord, or email when specific events occur.

If a platform is not listed as a built-in destination in PixelsCleared, webhooks are the way to connect it.

Set Up a Webhook Destination

1. Open the PixelsCleared dashboard.
2. Go to Gateway > Destinations.
3. Click Add Destination and select Custom Webhook.
4. Enter your Endpoint URL (the HTTPS URL that will receive the POST requests).
5. Optionally add Custom Headers -- key-value pairs sent with every request. Use this for authentication tokens, API keys, or content-type overrides.
6. Choose which event types to forward.
7. Click Save.

PixelsCleared sends a test request to the URL when you save. The endpoint must respond with a 2xx status code within 10 seconds for validation to pass.

Payload Format

PixelsCleared sends events as JSON in the POST body. Here is an example payload:

{
  "event_id": "evt_a1b2c3d4e5",
  "event_type": "lead",
  "timestamp": "2026-05-15T14:30:00Z",
  "consent": {
    "granted": true,
    "source": "cookieyes",
    "timestamp": "2026-05-15T14:29:55Z"
  },
  "data": {
    "page_domain": "www.example.com",
    "page_path": "/contact",
    "page_referrer_domain": "google.com",
    "custom_params": {
      "form_id": "quote-request",
      "category": "services"
    }
  },
  "metadata": {
    "gateway_tenant": "acme-corp",
    "scrubbed_fields": ["page_title", "query_string"],
    "destination_id": "dest_x9y8z7"
  }
}

Fields that were removed by the scrubbing engine are listed in metadata.scrubbed_fields so your receiving system knows what was excluded.

Consent Headers

Every webhook request includes consent information in the HTTP headers so your receiving system can make processing decisions without parsing the body:

• X-Consent-Granted -- true or false
• X-Consent-Source -- the consent tool that was detected (for example, cookiebot, onetrust, generic)
• X-Consent-Timestamp -- ISO 8601 timestamp of when consent was captured

If consent was not detected, X-Consent-Granted is set to false and X-Consent-Source is set to none.

Retry Behavior

PixelsCleared retries failed webhook deliveries with exponential backoff:

• 1st retry -- after 30 seconds
• 2nd retry -- after 2 minutes
• 3rd retry -- after 15 minutes

If all retries fail, the event is marked as delivery failed in the PixelsCleared Events log. You can view failed deliveries in Gateway > Events and manually retry them.

Testing Your Webhook

Before going live, verify that your endpoint receives and processes events correctly:

1. Use a request inspection tool like RequestBin or Webhook.site to generate a temporary endpoint URL.
2. Paste the URL into PixelsCleared as a webhook destination.
3. Trigger events from your website and inspect the incoming payloads in the tool's interface.
4. Verify that the payload structure, consent headers, and event data match your expectations.
5. Once confirmed, update the destination URL to your production endpoint.

For local development, you can use ngrok or localhost.run to expose a local server and inspect requests in real time.