Webhook Delivery

Webhook Delivery

Use case: reliably fan-out events to third-party endpoints (analytics, billing, partners) with guaranteed-delivery semantics and verifiable authenticity.

Why SendPromptly

  • Per-endpoint HMAC signing (X-SP-Signature: v1=) and timestamp verification to ensure authenticity.
  • SSRF validation and HTTPS-only endpoints to reduce risk.
  • Delivery runs are per-endpoint (fan-out) so each endpoint gets atomic retry behavior and clear audit logs.

Delivery headers and verification

  • X-SP-Event-Key: the event name
  • X-SP-Message-Id: ULID for tracing/dedup
  • X-SP-Timestamp: unix timestamp
  • X-SP-Signature: v1=<hex> — HMAC-SHA256 over {timestamp}.{body} using the endpoint secret

Verification steps for receivers

  1. Ensure X-SP-Timestamp is within 5 minutes of your server clock.
  2. Recompute HMAC-SHA256 over the string {timestamp}.{raw_body} with your stored secret.
  3. Use a constant-time comparison with the header signature.

Retry & failure semantics

  • Success is 2xx only; non-2xx triggers retries at 0s, +1m, +10m, +1h, +6h.
  • Webhook attempts time out at 30s.
  • Retries do not double-count usage; usage increments once per delivery_run on first success.

Operational tips

  • Use the portal Test Webhook button to validate configuration and inspect attempt logs.
  • Rotate signing secrets periodically; portal stores secrets encrypted and supports secret rotation.
  • If an endpoint is temporarily down, use the portal to replay failed deliveries after remediation.

Example: order.paid fan-out

  1. POST /api/v1/events with event_key: order.paid.
  2. DeliveryPlanner creates one delivery_run per configured webhook endpoint.
  3. Each endpoint receives an independently retried POST with the headers above.