Webhook Secrets

Learn how to manage the signing secret used to verify webhook deliveries.

Overview

A webhook secret is a 64-character random string used to sign webhook payloads. When Flintn sends a webhook to your endpoint, it computes an HMAC-SHA256 signature of the request body using your secret and includes it in the X-Signature-Primary header.

By verifying this signature, you can confirm that:

1. The request originated from Flintn (not an attacker)

2. The payload hasn't been modified in transit

One Secret Per Merchant

Each merchant has one webhook secret that is shared across all webhooks for that merchant. This simplifies secret management while maintaining security.

Creating a Webhook Secret

1. Go to hub.flintn.com/developers

2. Navigate to Webhooks > Webhook Secret

3. Click Create Secret

4. Copy and securely store the secret immediately

Important: The full webhook secret is displayed only once when created. If you lose it, you'll need to rotate the secret to get a new one.

Viewing Your Secret

After creation, you can view metadata about your webhook secret from the dashboard at hub.flintn.com/developers. The full secret value is masked — only the first 6 and last 4 characters are visible.

Rotating Your Secret

If your webhook secret is compromised or as part of regular security hygiene, you should rotate it:

1. Go to hub.flintn.com/developers

2. Navigate to Webhooks > Webhook Secret

3. Click Rotate Secret

4. Copy and securely store the new secret immediately

Important: After rotation, the old secret is immediately invalidated. Update your webhook handler with the new secret before rotating, or be prepared to quickly deploy the new secret after rotation.

Security Best Practices

Store Secrets Securely

• Use environment variables or a secrets manager (AWS Secrets Manager, HashiCorp Vault, etc.)

• Never hardcode secrets in your application code

• Never commit secrets to version control

# Good: Environment variable
export FLINTN_WEBHOOK_SECRET="whsec_xxx..."

# Bad: Hardcoded in code
const secret = "whsec_xxx..."; // Don't do this!

Never Log Secrets

Ensure your logging configuration doesn't capture the webhook secret or signature verification details that could expose it.

Rotate Periodically

Rotate your webhook secret periodically (e.g., every 90 days) as part of your security practices, even if you don't suspect compromise.

Rotate Immediately If Compromised

If you suspect your webhook secret has been exposed:

1. Rotate the secret immediately via the dashboard

2. Update your webhook handler with the new secret

3. Review webhook delivery logs for suspicious activity

Using the Secret

See Configure Webhooks for complete code examples showing how to verify webhook signatures using your secret.

Quick Reference

The signature is computed as:

signature = Base64(HMAC-SHA256(webhook_secret, request_body))

And sent in the header:

X-Signature-Primary: <base64-encoded-signature>

Next Steps

• Configure Webhooks - Set up webhook endpoints and verification

• Webhooks Overview - Learn about available events