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 shows the raw body and headers so you can compare what arrived with what your verifier expects. Production verification always belongs in your server code following the provider’s documentation.
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.