Webhook security
Webhook endpoints are public URLs. Treat them like any internet-facing API: assume abuse, replay, and spoofing unless you validate every request.
Always verify signatures
Providers sign payloads with a shared secret. Your handler must:
- Read the raw request body (before JSON parsing) when the provider requires it for HMAC.
- Recompute the signature using the provider’s algorithm (often HMAC-SHA256).
- Compare using a constant-time comparison to prevent timing attacks.
HookNexus can help you inspect signatures; use the Signature verification guide and API for testing. Production verification still belongs in your server code.
Use HTTPS endpoints
- Configure providers to send webhooks to HTTPS URLs only.
- Terminate TLS at a trusted edge (CDN, load balancer, or PaaS).
- Avoid mixed HTTP in production; it exposes payloads and secrets on the wire.
Protect API keys and secrets
| Do | Don’t |
|---|---|
| Store secrets in environment variables or a secrets manager | Commit secrets to git or paste them into frontend code |
| Rotate keys when staff leave or after a leak | Share one key across unrelated services |
| Use separate signing secrets per environment (dev/staging/prod) | Reuse production secrets in local .env files that get copied around |
HookNexus API keys should be treated like passwords: never embed them in client-side JavaScript bundles.
Implement idempotency
Networks retry; providers duplicate deliveries. Use a stable event id (e.g. Stripe-Event-Id, GitHub delivery header) to detect duplicates and return 200 without re-running side effects.
Validate payload structure
- Schema-validate JSON (type, required fields, enums) before business logic.
- Reject oversized bodies at the edge if your framework allows.
- Log validation failures at warn level with request id—avoid logging full secrets.
IP allowlisting (optional)
Some providers publish IP ranges for webhook senders. Allowlisting can reduce noise but:
- Ranges change; subscribe to provider updates.
- Not all providers offer stable IPs; don’t rely on allowlisting alone.
- Combine with signature verification for defense in depth.