Signatures, retries, and security

Compute HMAC-SHA256 over timestamp + "." + rawBody using the endpoint secret. Compare the lowercase hexadecimal digest to the value after v1= with a constant-time comparison.

import crypto from 'node:crypto';

export function verifyPromptessorWebhook(rawBody, headers, secret) {
  const timestamp = headers['x-promptessor-timestamp'];
  const supplied = headers['x-promptessor-signature']?.replace(/^v1=/, '');
  if (!timestamp || !supplied) return false;

  // Reject stale timestamps in your application before processing the event.
  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${timestamp}.${rawBody}`)
    .digest('hex');

  const a = Buffer.from(expected, 'hex');
  const b = Buffer.from(supplied, 'hex');
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

• A delivery succeeds on any HTTP 2xx response.
• Each eligible delivery is claimed with a short lease so overlapping workers do not send it concurrently.
• Each attempt times out after 10 seconds.
• Redirects are rejected.
• Failed deliveries retry with exponential delays: approximately 60, 120, 240, 480, 960, 1,920, then up to 3,600 seconds.
• A delivery is abandoned after 8 total attempts.
• Webhook delivery records are retained for 30 days.

• Store the webhook secret in a secret manager.
• Allow only HTTPS and keep TLS certificates valid.
• Enforce a timestamp tolerance appropriate to your environment.
• Verify HMAC before trusting event type or payload data.
• Deduplicate deliveries in durable storage.
• Return 2xx only after durable acceptance.
• Process business logic from a queue.
• Alert on repeated verification failures and abandoned deliveries.
• Rotate the secret after suspected exposure and update the receiver atomically.