Perspection Outbound Webhooks: The Complete Guide to Custom Event Routing and HMAC-SHA256 Signature Verification

How do you create an outbound webhook in Perspection?

Creating a webhook requires a name and endpoint URL, plus 7 optional fields: description, enabled toggle, event filter, condition filter, retry count (0-10, default 3), timeout (1,000-30,000 ms, default 5,000), and HMAC-SHA256 secret key. The dashboard validates URL format and defaults webhooks to enabled.

Step-by-Step Webhook Creation

1. Open the Perspection dashboard and navigate to the workspace where the outbound webhook should be created. The workspace must have an active Perspection SDK installation sending events. For SDK installation instructions, see the Install Tracking on Your Website Guide.

2. Navigate to the Webhooks section within the workspace settings. The Webhooks page displays all existing webhook configurations in a responsive card grid (1 column on mobile, 2 columns on tablet, 3 columns on desktop).

3. Click the "Create Webhook" button in the top-right corner of the Webhooks page. The Create Webhook dialog opens as a modal overlay.

4. Enter the webhook name in the Name field. The name is a required field and should describe the webhook purpose (e.g., "Salesforce CRM Sync" or "Slack High-Value Alerts").

5. Enter the endpoint URL in the Endpoint URL field. The URL must be a valid, publicly accessible HTTPS URL. Perspection validates URL format on both the client side and server side before saving the webhook configuration. Localhost URLs will not receive deliveries in production environments.

6. Optionally add a description to provide additional context for team members who manage webhook configurations.

7. Set the enabled toggle. New webhooks default to enabled. Toggle the switch to disabled to save a webhook configuration without immediately activating event delivery.

8. Configure the retry count (default: 3, range: 0 to 10). The retry count determines how many times Perspection reattempts delivery after a failed HTTP request. Perspection uses exponential backoff for retry timing: the delay before retry attempt N equals 2^N seconds (2 seconds, 4 seconds, 8 seconds, 16 seconds, and so on).

9. Configure the timeout (default: 5,000 milliseconds, range: 1,000 to 30,000 milliseconds). The timeout defines how long Perspection waits for the receiving endpoint to respond before marking the delivery attempt as failed.

10. Click "Create" to save the webhook configuration. Perspection immediately begins evaluating incoming events against the webhook filters and delivering matching events to the configured endpoint.

Webhook Payload Structure

Every outbound webhook delivery sends an HTTP POST request with a JSON body containing the following fields:

{
  "event_id": "evt_abc123def456",
  "event_name": "purchase",
  "event_type": "purchase",
  "timestamp": "2026-02-27T09:15:32.000Z",
  "properties": {
    "value": 149.99,
    "currency": "USD",
    "order_id": "ORD-78901",
    "items": [
      { "product_id": "SKU-001", "name": "Widget Pro", "quantity": 2 }
    ]
  },
  "context": {
    "page": "/checkout/confirmation",
    "referrer": "https://www.google.com",
    "user_agent": "Mozilla/5.0...",
    "utm_source": "google",
    "utm_medium": "cpc"
  },
  "user_id": "usr_789xyz",
  "session_id": "sess_456abc"
}

{
  "event_id": "evt_abc123def456",
  "event_name": "purchase",
  "event_type": "purchase",
  "timestamp": "2026-02-27T09:15:32.000Z",
  "properties": {
    "value": 149.99,
    "currency": "USD",
    "order_id": "ORD-78901",
    "items": [
      { "product_id": "SKU-001", "name": "Widget Pro", "quantity": 2 }
    ]
  },
  "context": {
    "page": "/checkout/confirmation",
    "referrer": "https://www.google.com",
    "user_agent": "Mozilla/5.0...",
    "utm_source": "google",
    "utm_medium": "cpc"
  },
  "user_id": "usr_789xyz",
  "session_id": "sess_456abc"
}

{
  "event_id": "evt_abc123def456",
  "event_name": "purchase",
  "event_type": "purchase",
  "timestamp": "2026-02-27T09:15:32.000Z",
  "properties": {
    "value": 149.99,
    "currency": "USD",
    "order_id": "ORD-78901",
    "items": [
      { "product_id": "SKU-001", "name": "Widget Pro", "quantity": 2 }
    ]
  },
  "context": {
    "page": "/checkout/confirmation",
    "referrer": "https://www.google.com",
    "user_agent": "Mozilla/5.0...",
    "utm_source": "google",
    "utm_medium": "cpc"
  },
  "user_id": "usr_789xyz",
  "session_id": "sess_456abc"
}

HTTP Headers Sent with Every Delivery

Perspection attaches the following headers to every outbound webhook HTTP POST request:

Teams can also define custom headers in the webhook configuration. Custom headers are merged with the default Perspection headers and override any default header that shares the same key name.

How do you configure event filters and condition filters?

Webhooks support 2 filtering layers in sequence. The event filter uses "include" mode (deliver only listed types) or "exclude" mode (deliver everything except listed types). The condition filter applies property-level rules using 8 operators (equals, not equals, greater/less than, exists, contains) with AND logic -- every condition must pass.

Layer 1: Event Filter (Event Type Matching)

The event filter controls which event types reach the outbound webhook based on the event name. The event filter offers 2 modes:

1. Include mode -- Only events whose event_name matches one of the selected event types are delivered. When include mode is active and no events are selected, the webhook matches all events (an empty include list acts as a wildcard).

2. Exclude mode -- All events are delivered except those whose event_name matches one of the selected event types. When exclude mode is active and no events are selected, no events are delivered.

The Perspection webhook dialog presents 10 common event types as selectable badges for quick configuration:

• page_view

• track

• identify

• form_submission

• button_click

• purchase

• add_to_cart

• checkout_started

• user_signup

• user_login

Teams can also add custom event names by typing the event name into the custom event input field and pressing Enter. Custom event names appear as additional selectable badges below the common event list.

Layer 2: Condition Filter (Property-Level Rules)

The condition filter applies granular rules against any field in the event payload, including nested properties accessed via dot notation (e.g., properties.value, context.utm_source, properties.items.0.product_id). Each condition consists of 3 parts:

1. Field -- The dot-notation path to the event property being evaluated (e.g., properties.value).

2. Operator -- One of 8 supported operators.

3. Value -- The comparison value (not required for the exists operator).

The 8 Condition Filter Operators

AND Logic for Multiple Conditions

When multiple conditions are configured, all conditions must evaluate to true for the event to pass the condition filter. Perspection applies AND logic across all conditions. To illustrate with a practical example:

• Condition 1: properties.value >= 100

• Condition 2: properties.currency == "USD"

• Condition 3: context.utm_source exists

An event must have a value of 100 or greater AND a currency of USD AND a non-null utm_source to pass all 3 conditions and reach the webhook endpoint. If any single condition fails, Perspection filters the event and does not deliver the event to the webhook.

Filter Execution Order

Perspection evaluates the event filter first and the condition filter second. When the event filter rejects an event (because the event type does not match the include list or does match the exclude list), Perspection skips condition evaluation entirely. The two-layer filtering architecture reduces unnecessary property lookups and improves delivery performance.

How do you verify webhook signatures using HMAC-SHA256?

Perspection signs every webhook payload with HMAC-SHA256 using a per-webhook secret key and delivers the hex-encoded signature in the X-Perspection-Signature header. Receiving endpoints must compute the HMAC-SHA256 digest of the raw request body, compare it against the header value using constant-time comparison, and reject mismatches.

How Perspection Generates the Signature

The Perspection webhook delivery service follows a 3-step signing process for every outbound delivery:

1. Perspection serializes the event payload to a JSON string using JSON.stringify().

2. Perspection creates an HMAC-SHA256 hash using the webhook's secret_key as the HMAC key and the JSON string as the message.

3. Perspection encodes the resulting hash as a lowercase hexadecimal string and attaches the hex string to the X-Perspection-Signature header.

When no secret key is configured for a webhook, Perspection omits the X-Perspection-Signature header entirely. Perspection strongly recommends configuring a secret key for every production webhook.

Node.js/Express Signature Verification Example

const crypto = require('crypto');
const express = require('express');

const WEBHOOK_SECRET = process.env.PERSPECTION_WEBHOOK_SECRET;

app.post('/webhooks/perspection',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const signature = req.headers['x-perspection-signature'];

    const hmac = crypto.createHmac('sha256', WEBHOOK_SECRET);
    hmac.update(req.body);
    const expectedSignature = hmac.digest('hex');

    if (!crypto.timingSafeEqual(
      Buffer.from(signature, 'hex'),
      Buffer.from(expectedSignature, 'hex')
    )) {
      console.error('Invalid Perspection webhook signature');
      return res.status(401).send('Invalid signature');
    }

    const event = JSON.parse(req.body);
    console.log('Verified Perspection event:', event.event_name);

    res.status(200).send('OK');
  }
);

const crypto = require('crypto');
const express = require('express');

const WEBHOOK_SECRET = process.env.PERSPECTION_WEBHOOK_SECRET;

app.post('/webhooks/perspection',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const signature = req.headers['x-perspection-signature'];

    const hmac = crypto.createHmac('sha256', WEBHOOK_SECRET);
    hmac.update(req.body);
    const expectedSignature = hmac.digest('hex');

    if (!crypto.timingSafeEqual(
      Buffer.from(signature, 'hex'),
      Buffer.from(expectedSignature, 'hex')
    )) {
      console.error('Invalid Perspection webhook signature');
      return res.status(401).send('Invalid signature');
    }

    const event = JSON.parse(req.body);
    console.log('Verified Perspection event:', event.event_name);

    res.status(200).send('OK');
  }
);

const crypto = require('crypto');
const express = require('express');

const WEBHOOK_SECRET = process.env.PERSPECTION_WEBHOOK_SECRET;

app.post('/webhooks/perspection',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const signature = req.headers['x-perspection-signature'];

    const hmac = crypto.createHmac('sha256', WEBHOOK_SECRET);
    hmac.update(req.body);
    const expectedSignature = hmac.digest('hex');

    if (!crypto.timingSafeEqual(
      Buffer.from(signature, 'hex'),
      Buffer.from(expectedSignature, 'hex')
    )) {
      console.error('Invalid Perspection webhook signature');
      return res.status(401).send('Invalid signature');
    }

    const event = JSON.parse(req.body);
    console.log('Verified Perspection event:', event.event_name);

    res.status(200).send('OK');
  }
);

Python/Flask Signature Verification Example

import hmac
import hashlib
import os
from flask import Flask, request

WEBHOOK_SECRET = os.environ['PERSPECTION_WEBHOOK_SECRET']

@app.route('/webhooks/perspection', methods=['POST'])
def webhook():
    signature = request.headers.get('X-Perspection-Signature')
    payload = request.get_data()

    expected_signature = hmac.new(
        WEBHOOK_SECRET.encode(),
        payload,
        hashlib.sha256
    ).hexdigest()

    if not hmac.compare_digest(signature, expected_signature):
        return 'Invalid signature', 401

    event = request.get_json()
    print('Verified Perspection event:', event['event_name'])

    return 'OK', 200

import hmac
import hashlib
import os
from flask import Flask, request

WEBHOOK_SECRET = os.environ['PERSPECTION_WEBHOOK_SECRET']

@app.route('/webhooks/perspection', methods=['POST'])
def webhook():
    signature = request.headers.get('X-Perspection-Signature')
    payload = request.get_data()

    expected_signature = hmac.new(
        WEBHOOK_SECRET.encode(),
        payload,
        hashlib.sha256
    ).hexdigest()

    if not hmac.compare_digest(signature, expected_signature):
        return 'Invalid signature', 401

    event = request.get_json()
    print('Verified Perspection event:', event['event_name'])

    return 'OK', 200

import hmac
import hashlib
import os
from flask import Flask, request

WEBHOOK_SECRET = os.environ['PERSPECTION_WEBHOOK_SECRET']

@app.route('/webhooks/perspection', methods=['POST'])
def webhook():
    signature = request.headers.get('X-Perspection-Signature')
    payload = request.get_data()

    expected_signature = hmac.new(
        WEBHOOK_SECRET.encode(),
        payload,
        hashlib.sha256
    ).hexdigest()

    if not hmac.compare_digest(signature, expected_signature):
        return 'Invalid signature', 401

    event = request.get_json()
    print('Verified Perspection event:', event['event_name'])

    return 'OK', 200

7 Security Best Practices for Webhook Signature Verification

1. Always use constant-time comparison -- Use crypto.timingSafeEqual() in Node.js or hmac.compare_digest() in Python. Standard string equality operators (=== or ==) are vulnerable to timing attacks that can leak the expected signature byte by byte.

2. Parse the raw request body -- Compute the HMAC against the raw byte string of the HTTP request body, not against a parsed-and-re-serialized JSON object. Re-serializing the JSON body may reorder keys or alter whitespace, producing a different hash.

3. Store the secret key in environment variables -- Never hardcode webhook secret keys in application source code. Use environment variables, secrets managers (AWS Secrets Manager, Google Cloud Secret Manager, HashiCorp Vault), or encrypted configuration stores.

4. Enforce HTTPS on the receiving endpoint -- Webhook payloads may contain personally identifiable information (PII) including email addresses, phone numbers, and user IDs. Transmitting webhook payloads over unencrypted HTTP exposes customer data to interception.

5. Validate the event payload schema -- After verifying the signature, validate that the event payload contains the expected fields (event_id, event_name, timestamp, properties) before processing the event. Schema validation prevents unexpected data structures from causing runtime errors.

6. Implement idempotency using the X-Perspection-Event-ID header -- Perspection may deliver the same event more than once due to retry logic. Use the X-Perspection-Event-ID header value as an idempotency key. Store processed event IDs in a cache (Redis, in-memory set, or database) and skip events that have already been processed.

7. Return HTTP 200 within 5 seconds -- Perspection defaults to a 5,000-millisecond timeout. If the receiving endpoint does not respond within the configured timeout, Perspection marks the delivery as failed and schedules a retry. Process webhook events asynchronously (e.g., enqueue the event for background processing) and return HTTP 200 immediately.

How do you monitor webhook delivery in Perspection?

The dashboard provides 3 monitoring layers: summary statistics on each webhook card (total, successful, and failed deliveries plus success rate); a detailed delivery log with HTTP status codes, response latency, and error messages; and a built-in test function that validates filter matching against a sample event without sending an HTTP request.

Webhook Card Statistics

Each webhook configuration displays as a card on the Webhooks page. Every webhook card shows the following real-time statistics:

1. Total Deliveries -- The cumulative count of delivery attempts Perspection has made to the webhook endpoint since the webhook was created.

2. Successful Deliveries -- The count of deliveries that received an HTTP 2xx response from the endpoint.

3. Failed Deliveries -- The count of deliveries that received a non-2xx response, timed out, or encountered a connection error.

4. Success Rate -- Calculated as (successful_deliveries / total_deliveries) * 100, displayed as a percentage with one decimal place. The success rate badge uses color coding: green for healthy delivery rates, red for failing webhooks.

5. Last Delivery Timestamp -- The date and time of the most recent delivery attempt.

6. Last Delivery Error -- When the most recent delivery failed, the webhook card displays the error message (e.g., "ECONNREFUSED", "timeout", "HTTP 502").

Webhook Status Indicators

Each webhook card displays a status icon based on the last delivery result:

• Green checkmark -- The last delivery succeeded (status: delivered).

• Red X circle -- The last delivery failed (status: failed).

• Amber spinning arrow -- A delivery is currently being retried (status: retrying).

• Gray clock -- The webhook is disabled or has not yet received a delivery attempt.

Delivery Logs

Clicking into a webhook configuration opens the delivery log, which displays individual delivery attempts in reverse chronological order (most recent first). Each delivery log entry includes:

The delivery log supports pagination with configurable limits (default: 50 entries per page) and offset-based navigation for reviewing historical delivery data.

Retry Behavior and Exponential Backoff

When a delivery attempt fails, Perspection schedules a retry using exponential backoff. The retry delay calculation follows the formula 2^attempt_number seconds:

1. Attempt 1 fails -- Retry scheduled after 2 seconds.

2. Attempt 2 fails -- Retry scheduled after 4 seconds.

3. Attempt 3 fails -- Retry scheduled after 8 seconds.

4. Attempt 4 fails -- Retry scheduled after 16 seconds.

5. Subsequent attempts -- Continue doubling until the configured retry count is exhausted.

After all retry attempts are exhausted, Perspection marks the delivery as permanently failed and stops attempting delivery for the specific event. The background retry worker processes up to 100 pending retries per cycle, fetching the original event payload from the events.raw_events table and redelivering the event with the next attempt number.

Testing Webhook Filter Configuration

The Perspection dashboard includes a "Test" button on each webhook card. Clicking "Test" sends a sample event through the webhook filter engine without making an HTTP request to the endpoint URL. The test function evaluates the sample event against both the event filter and condition filter and returns one of 2 results:

• Test passed -- The sample event matches the filters and would be delivered to the endpoint.

• Test failed -- The sample event does not match the filters. Perspection displays the specific reasons for the mismatch, including whether the event filter or condition filter rejected the event and which individual conditions failed.

The test sample event contains the following default payload:

{
  "event_id": "test_1740652800000",
  "event_name": "test_event",
  "event_type": "test",
  "timestamp": "2026-02-27T12:00:00.000Z",
  "properties": {
    "test": true,
    "value": 100
  },
  "context": {
    "page": "/test"
  }
}

{
  "event_id": "test_1740652800000",
  "event_name": "test_event",
  "event_type": "test",
  "timestamp": "2026-02-27T12:00:00.000Z",
  "properties": {
    "test": true,
    "value": 100
  },
  "context": {
    "page": "/test"
  }
}

{
  "event_id": "test_1740652800000",
  "event_name": "test_event",
  "event_type": "test",
  "timestamp": "2026-02-27T12:00:00.000Z",
  "properties": {
    "test": true,
    "value": 100
  },
  "context": {
    "page": "/test"
  }
}

Teams should verify that the webhook filter configuration produces the expected test result before enabling the webhook for production traffic.

For a detailed understanding of how Perspection processes and enriches events before webhook delivery, see the Perspection Home Dashboard Guide, which covers the 5-stage processing pipeline.

Methodology

All outbound webhook configuration options, event filtering capabilities, and HMAC signature verification details in this guide were verified against the Perspection production dashboard as of February 2026.

"Outbound webhooks solve a fundamental problem in customer data infrastructure: every team has at least one system that no CDP natively integrates with. Rather than building custom connectors for every internal tool, outbound webhooks give engineering teams a universal escape hatch. The two-layer filter architecture -- event type matching followed by property-level conditions -- was designed to prevent webhook endpoints from drowning in irrelevant traffic. A typical e-commerce site generates 50 to 100 page view events for every purchase event. Without event-level filtering, a CRM webhook would receive 99 percent noise. The condition filter adds the second level of precision: routing only high-value purchases or purchases from specific UTM campaigns to alerting endpoints. The exponential backoff retry strategy (2, 4, 8, 16 seconds) balances delivery reliability against overwhelming a temporarily unhealthy endpoint. Teams should always configure a secret key and verify HMAC-SHA256 signatures on the receiving side -- an unsigned webhook endpoint is functionally an unauthenticated public API that accepts writes from anyone who discovers the URL."

-- Perspection Product Engineering Team

Sources and References

1. HMAC -- RFC 2104, https://datatracker.ietf.org/doc/html/rfc2104

2. Webhooks Best Practices, https://webhooks.fyi/best-practices/

3. Perspection Product Guide -- Event Transformers, /library/event-transformers-field-mapping-guide

4. Perspection Product Guide -- Home Dashboard, /library/home-dashboard-guide