Webhooks

Webhook configuration is stored with an API key, and delivered task and billing events belong to that key's team workspace. Webhook delivery and polling can coexist; polling remains the recovery path if a receiver is unavailable.

Delivery model

• Task events: task.succeeded, task.failed, and task.canceled
• Billing events: balance.low and credits.granted
• running progress is not pushed in v1
• Each payload is { id, type, created_at, api_version, data }

Signing

Headers:

• Yeehoo-Event
• Yeehoo-Signature: t=<unix>,v1=<hex>
• X-Yeehoo-Delivery-ID

Verify v1 with HMAC-SHA256(secret, "{timestamp}.{raw_body}"). Read the raw body, validate timestamp freshness, deduplicate by id or delivery ID, and return 2xx before doing slow work.

Retries

• timeout: 5 seconds
• max attempts: 8
• backoff: min(2^n * 10s, 6h) with ±20% jitter
• only 429, 5xx, and network timeouts are retried
• 20 consecutive failures disable an endpoint; re-enable it after fixing the receiver