Guides›Webhooks

Webhooks

Last updated 2026-02-13

Webhook signing uses HMAC SHA-256 over the raw request body.

Headers:

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

Always verify signatures before processing payload.

Example events

  • message.responded
  • agent.started
  • agent.error

Payload shape depends on event, but always includes an event and data object.

Retry processing

Rooaak processes failed webhook retries using the internal cron endpoint:

  • GET/POST /api/cron/webhooks
  • Auth: Authorization: Bearer $CRON_SECRET

For hosted Rooaak, this scheduler is managed by Rooaak infrastructure. Customers only need to keep their webhook receiver available and idempotent.

Receiver requirements

  • Deduplicate by X-Rooaak-Delivery.
  • Store the webhook secret securely (it is only returned on creation).
  • Process asynchronously and return 2xx quickly (enqueue work), otherwise Rooaak will retry.

Channel correlation fields

message.responded webhook payloads can include additive adapter fields:

  • data.metadata (original message metadata)
  • data.channel (if metadata.channel is provided)
  • data.correlationId (if metadata.correlationId is provided)
  • data.responseTimeMs (runtime response latency)

Use these to map Rooaak responses back to Slack threads, WhatsApp message IDs, or custom app conversations.