Skip to main content
Use this page to quickly see which events Blaaiz emits and what every webhook payload contains.

​
Event types

Your business has two webhook URLs: collection_url and payout_url. The table below shows every event and which URL it is delivered to.
All events except payout events are delivered to your collection_url. Register both URLs via the Webhook API.

​
Payload structure

All webhook payloads include:
  • event — The event type
  • data — The event data object
  • timestamp — When the event occurred
  • signature — HMAC signature for verification (header: x-blaaiz-signature)
Always verify the x-blaaiz-signature using your webhook signing_secret to ensure the webhook originates from Blaaiz.

​
Webhook retries

We retry deliveries with exponential backoff and jitter to avoid thundering herds.
  • Attempts: up to 10 total
  • Initial backoff: 5 minutes
  • Backoff factor: 2x per attempt
  • Max backoff cap: 24 hours (1440 minutes)
  • Jitter: 80–120% randomization on each delay
  • Success: any HTTP 2xx response stops retries
  • Any non-2xx (4xx/5xx/timeout/connection error) triggers the next retry
Approximate schedule (actual delays vary ±20% because of jitter): After 10 failed attempts, the webhook is marked permanently failed and no further automatic retries occur. You can manually replay via the API.
⚙️ Best practices
  • Reply with a 2xx quickly (within 30 seconds) and process work asynchronously if needed.
  • Implement idempotency using the event_id so duplicate deliveries don’t double-process work.
  • Return non-2xx only when you truly want a retry.

​
Data retention

Webhook logs (payloads, responses, attempt history) are retained for 90 days. After 90 days, records are pruned for both successful and failed deliveries.
  • If you need webhook data beyond 90 days, store it in your own systems.
  • Replay is only available for webhooks within the 90-day window.