Key rotation lets you replace a signing secret without dropping deliveries during the transition. DMSI Webhooks supports a 24-hour dual-signature window to allow a smooth rollover.

When to Rotate #

• Suspected secret compromise
• Routine security rotation policy
• Lost secret (cannot be recovered without rotation)
• Staff change who had access to the secret

How to Rotate #

1. Go to DDLS > Webhooks > Endpoints
2. Click Edit on the endpoint
3. Click Rotate Secret
4. Copy the new secret immediately — it is shown only once
5. Update your receiving server to accept the new secret

The Dual-Signature Window #

During the 24 hours following a rotation, DMSI Webhooks sends both the old and the new signature in the X-DMSI-Signature header, separated by , (comma-space):

X-DMSI-Signature: sha256=<new_signature>, sha256=<old_signature>

Your receiver should accept either signature during this window:

$signatures = explode(', ', $_SERVER['HTTP_X_DMSI_SIGNATURE'] ?? '');
$string_to_sign = $timestamp . '.' . $webhook_id . '.' . $raw_body;
$accepted = false;
foreach ($secrets as $secret) {
$expected = 'sha256=' . hash_hmac('sha256', $string_to_sign, $secret);
foreach ($signatures as $sig) {
if (hash_equals($expected, trim($sig))) {
$accepted = true;
break 2;
}
}
}
if (!$accepted) {
http_response_code(401);
exit('Invalid signature');
}

After 24 Hours #

The old secret is automatically cleared by the daily cleanup cron. After 24 hours, only the new secret is valid and the X-DMSI-Signature header returns to a single value.

Related Topics #

• Signing Secret Management
• Signature Verification
• Delivery Logs Overview