Skip to main content

Request Signing

Webhook requests must be signed using a shared secret. The X-Webhook-Signature header supports multiple signatures, with each signature separated by a comma (,) and each signature version prefixed by the version number (e.g., v1) and an equals sign (=).

Signature v1​

To sign a request, compute an HMAC-SHA-256 digest over the exact request body followed by the X-Webhook-Timestamp and X-Webhook-Id header values, in that order with no separators, using the shared secret key. Encode the digest as a hex string and add it to the X-Webhook-Signature request header with the v1= prefix. The webhook ID is case-sensitive and must be included exactly as sent.

NodeJS example​

// Prepare event payload
const body = JSON.stringify({
type: 'test.ping',
version: '1',
data: { message: 'ping!' },
})
const webhookId = crypto.randomUUID()

// Append timestamp and webhook ID to body
const timestamp = Math.floor(Date.now() / 1000).toString()
const hashPayload = body + timestamp + webhookId

// Create signature with payload + hmac secret
const hmac = crypto.createHmac('sha256', secretKey)
const signature = hmac.update(hashPayload).digest('hex')

// Prepare request
const request = new Request($url, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-Webhook-Id': webhookId,
'X-Webhook-Key-Id': secretKey.slice(0, 8),
'X-Webhook-Signature': `v1=${signature}`,
'X-Webhook-Timestamp': timestamp,
},
body
})

PHP example​

// Prepare event payload
$body = json_encode([
'type' => 'test.ping',
'version' => '1',
'data' => ['message' => 'ping!'],
]);
$webhookId = bin2hex(random_bytes(16));

// Append timestamp and webhook ID to body
$timestamp = (string) round(microtime(true));
$payload = $body . $timestamp . $webhookId;

// Create signature with payload + hmac secret
$signature = hash_hmac('sha256', $payload, $secretKey);

// Prepare request
$curl = curl_init($url);
curl_setopt_array($curl, [
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => $body,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
'X-Webhook-Id: ' . $webhookId,
'X-Webhook-Key-Id: ' . substr($secretKey, 0, 8),
'X-Webhook-Signature: v1=' . $signature,
'X-Webhook-Timestamp: ' . $timestamp,
],
]);