Webhooks

Webhooks let you receive real-time HTTP notifications whenever consent events occur in your eConsent properties. Instead of polling the API, your server is notified immediately when a certificate is created, consent is revoked, or other key events fire.

Supported events

Subscribe to any combination of the following event types:

Event	Description
session.certificate.created	A new consent certificate was generated
meta.certificate.created	A Meta (Facebook) lead certificate was generated
session.created	A new tracking session was initialized
consent.granted	A user granted consent on a tracked form
consent.revoked	A previously granted consent was revoked
high_risk.detected	A session was flagged as high-risk

Creating a webhook

1. Navigate to Channels > Webhooks in your dashboard at app.econsent.org.
2. Click Add Endpoint.
3. Configure the endpoint:
   • URL: The HTTPS endpoint that will receive webhook payloads. Must be a publicly accessible URL (localhost and private addresses are rejected).
   • HTTP Method: Choose POST, PUT, PATCH, or GET. Defaults to POST.
   • Events: Select which event types this endpoint should receive. If none are selected, the endpoint receives all events.
4. Click Save. A unique signing secret is generated and displayed once. Copy it immediately.

Caution

Each property supports a maximum of 25 webhook endpoints. Remove unused endpoints before creating new ones.

Payload structure

Every webhook delivery sends a JSON payload with this structure:

{
  "event": "session.certificate.created",
  "timestamp": "2026-04-02T14:30:00.000Z",
  "data": {
    "certificateId": "cert-abc123",
    "sessionId": "sess-xyz789",
    "propertyId": "prop-456",
    "consumerPhone": "+15551234567",
    "consumerName": "Jane Doe",
    "consentText": "I agree to be contacted...",
    "ipAddress": "203.0.113.42",
    "userAgent": "Mozilla/5.0..."
  }
}

The data object contents vary by event type. Certificate events include the full certificate record; session events include session metadata.

HMAC-SHA256 signature verification

Every webhook delivery is signed so you can verify it originated from eConsent. Three headers are included with each request:

Header	Description
X-EConsent-Signature	HMAC-SHA256 hex digest of {timestamp}.{body}
X-EConsent-Timestamp	Unix timestamp (milliseconds) when the payload was signed
X-EConsent-Event	The event type (e.g. session.certificate.created)

Verifying the signature

To verify, reconstruct the signed content by concatenating the timestamp, a period, and the raw request body. Then compute the HMAC-SHA256 using your endpoint’s signing secret and compare it to the X-EConsent-Signature header.

const crypto = require('crypto');

function verifyWebhookSignature(req, secret) {
  const signature = req.headers['x-econsent-signature'];
  const timestamp = req.headers['x-econsent-timestamp'];
  const body = JSON.stringify(req.body);

  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${timestamp}.${body}`)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature, 'hex'),
    Buffer.from(expected, 'hex')
  );
}

Tip

Always use a constant-time comparison (like crypto.timingSafeEqual) to prevent timing attacks when validating signatures.

Field mapping

Field mapping lets you transform the default eConsent payload into the format your CRM or downstream system expects. This is configured per endpoint when creating or editing a webhook.

Field mappings

Map eConsent fields to custom field names using dot-path notation for the source:

Source (eConsent field)	Target (your field name)
data.consumerPhone	phone_number
data.consumerName	full_name
data.certificateId	cert_id

With these mappings, instead of receiving the full default payload, your endpoint receives:

{
  "phone_number": "+15551234567",
  "full_name": "Jane Doe",
  "cert_id": "cert-abc123"
}

Static fields

Add fixed key-value pairs to every payload. Useful for identifying the source system or routing within your CRM:

Key	Value
source	econsent
campaign_id	summer-2026

Include raw payload

Enable the Include Raw Payload option to append the original, untransformed payload under a _raw key alongside your mapped fields.

Retry logic

Webhook delivery uses a fire-and-forget model with retries for network-level failures only:

• Attempts: 3 total (1 initial + 2 retries)
• Backoff: Exponential starting at 10 seconds (10s, 20s, 40s)
• Retry triggers: DNS failures, connection refused, and request timeouts (5-second timeout per attempt)
• Non-retry cases: Any HTTP response (including 4xx and 5xx) is treated as a successful delivery. Only network errors trigger retries.

Note

Because any HTTP status code is accepted, your endpoint does not need to return a 200 response. However, returning a 2xx status is still recommended as a best practice.

Testing

Use the Test button next to any configured webhook endpoint in the dashboard to send a test ping. This enqueues a test.ping event with the following payload:

{
  "event": "test.ping",
  "timestamp": "2026-04-02T14:30:00.000Z",
  "data": {
    "message": "This is a test webhook from eConsent"
  }
}

The test payload is signed with your endpoint’s secret, so you can use it to verify your signature validation logic before going live.

Next steps

• Properties & Domains. Configure the properties that generate webhook events
• Retention Management. Control how session data is stored and retained
• Revocation & Opt-Out. How consent revocation triggers webhook events