Webhooks

Warpweb sends two kinds of outbound webhooks:

• Form Submissions — fired when someone fills out a form on a deployed site. The thing you almost certainly want.
• Revision Status — fired when an async build or revision completes or fails. Optional but recommended over polling.

All webhooks are signed with HMAC-SHA256 using a per-resource secret. Always verify signatures — see Verifying Signatures for copy-paste snippets in multiple languages.

Common conventions

• All deliveries are POST with Content-Type: application/json.
• All payloads include an event_id (UUID). Use it as your idempotency key — duplicates can happen.
• Signature lives in the X-Warpweb-Signature header.
• User-Agent is Warpweb-Webhook/1.0.
• Connection timeout: 10 seconds. Return a 2xx response within that window.
• Retry schedule on 5xx / network errors: immediate, +30s, +5min. After that, dead-letter.
• 4xx responses are not retried — they’re treated as permanent rejections.

Endpoint requirements

Your webhook receiver should:

1. Verify X-Warpweb-Signature against the raw request body using your stored secret.
2. Parse JSON and inspect event_type.
3. Dedupe on event_id if you’ve seen it before — return 200 immediately for duplicates.
4. Process the event, or enqueue it for async processing.
5. Return 2xx within 10 seconds.

If your processing is slow, enqueue and return 200 immediately. Don’t make Warpweb wait — it’s better to acknowledge fast and retry on your own queue than to time out and trigger our retry loop.