POST /v1/sites/:id/webhooks/forms

Configure where form submissions on a deployed site get delivered. Warpweb POSTs each submission to your URL with an HMAC-SHA256 signature.

Until a webhook URL is configured, form submissions deliver as plain email to the contact_email you passed at site creation. Most API customers want the webhook path — it gives you structured JSON and signature verification.

Cost: Free to configure. Each delivery is free.

Request

curl -X POST https://api.warpweb.ai/v1/sites/site_8f3c2a1b/webhooks/forms \
  -H "Authorization: Bearer wpwb_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.yourapp.com/webhooks/warpweb-leads",
    "secret": "whsec_pickAnythingLongAndRandom"
  }'

Body

Field	Type	Required	Description
`url`	string	yes	Your HTTPS endpoint. Must be reachable from the public internet. HTTP URLs are rejected.
`secret`	string	yes	The signing secret. Store it on your end too — you’ll use it to verify the signature on every delivery. Min 16 chars; recommended 32+.

Response

{
  "site_id": "site_8f3c2a1b-5d47-4c9e-b820-1f8a3e7d9c4f",
  "form_webhook_url": "https://api.yourapp.com/webhooks/warpweb-leads",
  "configured_at": "2026-05-17T15:42:11Z"
}

We never return the secret — store it carefully on your end. To rotate, call this endpoint again with a new secret; the old one is invalidated.

What gets delivered

See Webhooks → Form Submissions for the full payload contract, signature format, and retry behavior.

Sending a test payload

The dashboard at app.warpweb.ai has a “Send test webhook” button per site that fires a fake submission against your configured URL. Use it to verify signature validation end-to-end before pointing real traffic.

Errors

Status	Error	Cause
400	`invalid_url`	URL is malformed or uses HTTP.
400	`secret_too_short`	Secret must be at least 16 characters.
404	`site_not_found`	No site with that ID belongs to your account.
422	`url_not_reachable`	Optional preflight check: we tried OPTIONS or HEAD on your URL and got a connection error or 5xx. Fix your endpoint and retry.

POST /v1/domains/register Overview