> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zbx.boomfi.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhook Best Practices

> Idempotency, security, and operational patterns for reliable webhook handlers.

## Security

* Always [Verify Webhook Signatures](/webhooks/verify-signatures) before business logic
* Reject stale timestamps
* Check `org_id` so partner/metadata edge cases cannot cross orgs
* Serve only over HTTPS; do not log full headers if they include secrets from your own reverse proxies

## Correctness

* **Idempotency**: process by payment / subscription / invoice id; retries and replays will re-send the same business event
* Prefer updating state machines (`paid`, `active`) rather than incrementing counters without keys
* Persist the raw event id when available for audit

## Performance

* Return `2xx` after durable write (database commit or queue enqueue)
* Do slow work asynchronously *after* acknowledging, but ensure crash recovery from persisted events
* Keep response under a few seconds to avoid timeouts marking deliveries failed

## Configuration

* Keep webhook URL and public key in sync across environments
* Rotate keys deliberately; dual-run verification during rotations if possible
* Distinguish [request signing secrets](/authentication) from webhook RSA keys

## Observability

* Monitor non-2xx rates at your edge
* Review [event history](/webhooks/event-history-and-replay) weekly during early integration
* Alert when failed\_count grows

## Testing

1. Point webhook URL at a tunnel to local
2. Create a small paylink payment or use test tools
3. Confirm signature verification passes with dashboard public key
4. Force a handler error, confirm failed status, **Retry**, confirm success

## Related

* [Configure Webhooks](/webhooks/setup)
* [Event Types](/webhooks/event-types)