<?php
define('WEBHOOK_SECRET', 'my_webhook_secret');
define('WEBHOOK_TIMESTAMP_FRESHNESS_MINUTES', 5);

function validate_event($data, $sig, $timestamp)
{
    # Calculate Signature
    $calc_sig = base64_encode(hash_hmac('sha256', $timestamp . '.' . $data, WEBHOOK_SECRET, true));
    # Compare calculated and given signatures
    $sigValid = hash_equals($sig, $calc_sig);
    # Compare timestamp with now
    $diff = abs(floor((strtotime($timestamp) - time()) / 60));

    return $sigValid && $diff < WEBHOOK_TIMESTAMP_FRESHNESS_MINUTES;
}

# Extract the server signature from HTTP header
$sig = $_SERVER['Lucca-Signature'];

# Extract the server timestamp from HTTP header
$timestamp = $_SERVER['Lucca-Timestamp'];

# Extract the raw body
$data = file_get_contents('php://input');

# Validate
$valid = validate_event($data, $sig, $timestamp);

error_log('Webhook validation: '.var_export($valid, true));

if ($valid) {
    # Check for duplicates (you may have already received this event)
    # Do something with the event

    http_response_code(202);
} else {
    http_response_code(401);
}
?>

Signature

Validate signature in order to ensure authenticity.

Timestamp

Validate the timestamp in order to protect against replay attacks.

Deduplication

Check for duplicates.

You should refuse any event that does not have both the Lucca-Signature and the Lucca-Timestamp HTTP headers and return a 401 Unauthorized.

​
Lucca-Signature

Each event delivery is signed by the server in order for webhook endpoints to be able to check their authenticity.

The signature is a SHA256 hash calculated from the concatenation of both the delivery timestamp (i.e. the moment the event was sent from our server) and the request payload, separated by a . (dot) character. Both properties can be found in HTTP headers:

  • the signature is in the Lucca-Signature HTTP header ;
  • the timestamp is in the Lucca-Timestamp HTTP header.

If the signature is missing (i.e. no Lucca-Signature header was sent) or does not match, then return a 401 Unauthorized.

<content_to_hash> = <timestamp> '.' <body>

​
Lucca-Timestamp

The timestamp sent in the Lucca-Timestamp HTTP header matches the exact time the request was sent from Lucca’s servers. It is an UTC date-time in ISO 8601 format, e.g.: “2025-01-01T08:34:23Z”.

You should check the timestamp is within +/- 5 minutes from the moment your receive the event, in order to protect yourself against replay attacks.

If the timestamp is too old / too far in the future, or is simply missing, then return a 401 Unauthorized.

​
Handling Duplicates

You may want to check for duplicate events (and potentially discard them), as you may receive an event more than once through our retry feature.

<?php
define('WEBHOOK_SECRET', 'my_webhook_secret');
define('WEBHOOK_TIMESTAMP_FRESHNESS_MINUTES', 5);

function validate_event($data, $sig, $timestamp)
{
    # Calculate Signature
    $calc_sig = base64_encode(hash_hmac('sha256', $timestamp . '.' . $data, WEBHOOK_SECRET, true));
    # Compare calculated and given signatures
    $sigValid = hash_equals($sig, $calc_sig);
    # Compare timestamp with now
    $diff = abs(floor((strtotime($timestamp) - time()) / 60));

    return $sigValid && $diff < WEBHOOK_TIMESTAMP_FRESHNESS_MINUTES;
}

# Extract the server signature from HTTP header
$sig = $_SERVER['Lucca-Signature'];

# Extract the server timestamp from HTTP header
$timestamp = $_SERVER['Lucca-Timestamp'];

# Extract the raw body
$data = file_get_contents('php://input');

# Validate
$valid = validate_event($data, $sig, $timestamp);

error_log('Webhook validation: '.var_export($valid, true));

if ($valid) {
    # Check for duplicates (you may have already received this event)
    # Do something with the event

    http_response_code(202);
} else {
    http_response_code(401);
}
?>