Webhook format

Every webhook delivery is a signed POST with a JSON body of the same outer shape. To build a receiver, read Receive webhooks.

Envelope#

{
  "id": "4f1c2b9e-7d0a-4c55-9a51-2d8e6f0b3a17",
  "type": "consent.withdrawn",
  "createdOn": "2026-09-24T10:12:03.412Z",
  "projectId": "c2a6f0de-51b3-4f0a-9d7e-8b1f3a6c4e90",
  "test": false,
  "data": {}
}

Event types#

An endpoint receives only the event types ticked on it in the console. See Webhook endpoints.

Headers#

X-Piedap-Event: consent.withdrawn
X-Piedap-Timestamp: 1790000000
X-Piedap-Signature: sha256=a5e5e6ac6418826ab09e3bcaa2ffcfdb6d9b1b6ccb75f…

Signature#

The signature is the HMAC-SHA256 of the timestamp, a full stop and the raw body. The key is the endpoint's signing secret, whsec_…, shown once when the endpoint is created.

HMAC-SHA256(secret, "<X-Piedap-Timestamp>.<raw body>")

To check a delivery:

1. Read the raw body as bytes, before any JSON parser touches it.
2. Read X-Piedap-Timestamp. Refuse the delivery if it is more than 300 seconds from your clock, in either direction.
3. Compute the HMAC-SHA256 of the timestamp, a full stop and the raw body, keyed with the signing secret. Write it as lower-case hex.
4. Compare it with the value after sha256= in X-Piedap-Signature, using a constant-time comparison.

import {
  SIGNATURE_HEADER,
  TIMESTAMP_HEADER,
  verifyWebhook,
} from '@piedap/consent/server';

const ok = verifyWebhook({
  payload: rawBody,
  signature: req.get(SIGNATURE_HEADER),
  timestamp: req.get(TIMESTAMP_HEADER),
  secret: process.env.PIEDAP_WEBHOOK_SECRET,
});

import os
from piedap_consent import (
    SIGNATURE_HEADER,
    TIMESTAMP_HEADER,
    verify_webhook,
)

ok = verify_webhook(
    raw_body,
    request.headers.get(SIGNATURE_HEADER),
    request.headers.get(TIMESTAMP_HEADER),
    secret=os.environ["PIEDAP_WEBHOOK_SECRET"],
)

$payload   = file_get_contents('php://input');
$timestamp = $_SERVER['HTTP_X_PIEDAP_TIMESTAMP'] ?? '';
$signature = $_SERVER['HTTP_X_PIEDAP_SIGNATURE'] ?? '';
$secret    = getenv('PIEDAP_WEBHOOK_SECRET');

$fresh = ctype_digit($timestamp)
    && abs(time() - (int) $timestamp) <= 300;
$expected = 'sha256='
    . hash_hmac('sha256', $timestamp . '.' . $payload, $secret);

if (!$fresh || !hash_equals($expected, $signature)) {
    http_response_code(401);
    exit;
}

rawBody and raw_body are the body exactly as received. Each retry is signed again with a fresh timestamp, so a late retry still passes. The reasons behind each step are in Verify signatures.

Response and retries#

A delivery counts as made when your endpoint answers with a 2xx status within eight seconds. Anything else is a failure and is tried again: a redirect, another status, a timeout or a connection error.

Duplicates and order#

Related#

• Receive webhooks
• Match events to your users
• Webhook problems