Webhooks: Delivery, Security, and Best Practices

Webhooks

SendPromptly can fan out one event to multiple webhook endpoints so downstream systems stay in sync with customer-facing notifications.

Delivery model

• One delivery run per configured endpoint
• Success is any HTTP 2xx response
• Non-2xx responses are retried with exponential backoff
• Delivery attempts are visible in logs for debugging and replay workflows

Webhook delivery is at-least-once, so consumers should be idempotent.

Signature headers

Validate these headers before processing payloads:

• X-SP-Timestamp
• X-SP-Signature

Use HMAC-SHA256 over the raw request body and compare signatures in constant time.

Security checklist

1. Verify signature before parsing or mutating payload data.
2. Enforce a replay window using X-SP-Timestamp.
3. Reject stale or missing signature headers.
4. Return fast 2xx responses and move heavy work to async jobs.

Consumer reliability checklist

• Use idempotency keyed by event id or delivery id.
• Implement dead-letter handling for repeated failures.
• Track endpoint latency and failure rate by event key.
• Alert on sustained retry spikes.

Minimal handler pattern

1. Receive request and capture raw body.
2. Verify signature and timestamp tolerance.
3. Persist event metadata for traceability.
4. Enqueue asynchronous processing.
5. Return 200 quickly.

Deep-dive guides

• Webhook Signature Verification Pitfalls
• Webhook Retry Strategies
• Webhook Delivery Logs and Debugging