Webhook Security

Webhook security is critical to ensure that requests to your endpoint are actually coming from Sent and haven't been tampered with. This page covers how to verify webhook authenticity and implement security best practices.

Why Webhook Security Matters

Without proper verification, attackers could:

• Send fake webhook requests to trigger unwanted actions
• Modify payload data to manipulate your app
• Overload your webhook endpoint with requests

How Sent Signs Webhooks

Sent signs every webhook request with an HMAC-SHA256 signature computed from the webhook's signing secret. This creates a unique signature for each request that proves:

1. The request came from Sent
2. The payload hasn't been modified

Finding Your Secret Key

Each webhook endpoint has a unique secret that's used to sign all requests to that endpoint.

To access your webhook secret, you can click your desired webhook endpoint in your Sent Dashboard and click the Eye Icon button to view the secret, or you can click the Copy button to copy the secret to your clipboard.

Signature Verification

How Signatures Work

Each webhook request includes several headers for verification:

The signature format is:

x-webhook-signature: v1,{base64_encoded_signature}

The signature is computed as follows:

1. Strip the whsec_ prefix from your signing secret
2. Base64-decode the remaining secret to get raw key bytes
3. Concatenate: {webhookId}.{timestamp}.{payload} (dot-separated)
4. Compute HMAC-SHA256 using the raw key bytes
5. Base64-encode the result
6. Prefix with v1,

Step-by-Step Verification

Security Best Practices

Always Validate Signatures

Never trust a webhook request without signature verification:

// ❌ BAD - No verification
app.post('/webhook', (req, res) => {
  processWebhook(req.body); // Dangerous!
  res.status(200).send('OK');
});

// ✅ GOOD - Verified first
app.post('/webhook', (req, res) => {
  if (!verifySignature(req)) {
    return res.status(401).send('Unauthorized');
  }
  processWebhook(req.body);
  res.status(200).send('OK');
});

The example calls a verifySignature helper that implements the six steps in Step-by-Step Verification. Copy a complete implementation for your language from the verifier in seven languages, and always run it against the raw request body. A body parsed and re-serialized by your framework produces a different signature.

Use Timing-Safe Comparisons

Standard string comparison can leak timing information. Use dedicated functions:

• Node.js: crypto.timingSafeEqual()
• Python: hmac.compare_digest()
• Go: subtle.ConstantTimeCompare()
• Other languages: Look for "constant-time" or "timing-safe" comparison functions

Prefer HTTPS

Sent accepts both http:// and https:// endpoints at registration time, but you should always use HTTPS in production:

{
  "url": "https://your-app.com/webhook" // ✅ Recommended
}

{
  "url": "http://your-app.com/webhook" // ⚠️ Not recommended — payload travels in clear text
}