Webhook Lifecycle Guide

Lifecycle

1. Rooaak event is emitted (message.responded, agent.error, etc.).
2. Matching project webhooks are loaded from webhooks.
3. Delivery attempt is made and logged in webhook_deliveries.
4. Retryable failures are queued in webhook_queue.
5. /api/cron/webhooks processes pending retries with exponential backoff.

Signature verification

Rooaak signs every webhook payload:

• X-Rooaak-Delivery
• X-Rooaak-Event
• X-Rooaak-Signature: sha256=<hex>

Always verify HMAC on raw request body using your webhook secret.

Retry/backoff policy

Current backoff sequence:

1. 30 seconds
2. 2 minutes
3. 8 minutes
4. 32 minutes
5. 2 hours

Retry budget: max 5 attempts.

Retryability rules

Retryable:

• network errors/timeouts
• HTTP 429
• HTTP 5xx

Non-retryable:

• invalid URL
• redirect responses
• most HTTP 4xx errors

Scheduler ownership

For Rooaak-hosted deployments:

• Rooaak infrastructure owns cron execution for /api/cron/webhooks.

For self-hosted Rooaak:

• operators must schedule authenticated calls to /api/cron/webhooks.

Customers integrating via adapters do not run Rooaak cron jobs.

Console operator notes

• Webhook secrets are shown once on create/rotation in Console > Webhooks (/console/webhooks).
• Delivery history is available in the Delivery Logs panel (filter by webhook, event, and success/failed status).
• Retry state is available in the Retry Queue panel (pending, processing, failed with attempt counters and next-attempt timestamps).
• If retry queues stall, verify cron execution and auth for /api/cron/webhooks first.