Webhooks

Webhooks deliver real-time HTTP notifications to your server whenever a form submission event occurs. Formtorch sends a signed POST request to each configured endpoint.

How it works

1. A user submits your form
2. Formtorch processes the submission (spam check, storage)
3. For each active endpoint subscribed to the matching event, Formtorch enqueues a delivery job
4. The job sends a POST with the signed payload to your endpoint
5. Your server returns a 2xx response
6. Formtorch marks the delivery as successful

If your server returns a non-2xx response or times out, the delivery is retried automatically.

Setting up webhooks

Webhook endpoints are workspace-level: one endpoint can receive events from all your forms.

From the dashboard:

1. Go to Settings → Webhooks
2. Click Add Endpoint
3. Enter your endpoint URL (must be https://)
4. Select the events to subscribe to: form.submitted, form.spam, and/or form.test
5. Save and copy the signing secret (shown once)

Event types

See Webhook Events for full payload shapes.

Delivery model

• Each subscribed endpoint receives an independent delivery
• Delivery order is not guaranteed when a form has multiple endpoints
• Paused endpoints do not receive deliveries; queued jobs for a paused endpoint are dropped

Retry schedule

Your endpoint must respond within 30 seconds with a 2xx status.

If it fails, Formtorch retries with exponential backoff for up to 6 total attempts (1 initial + 5 retries). After all attempts are exhausted, the delivery is marked failed and can be retried manually from the delivery log in Settings → Webhooks.

Delivery log and manual retry

The delivery log for each endpoint is visible in Settings → Webhooks. It shows status, HTTP response code, and response time for recent deliveries. Failed deliveries have a Retry button.

Testing

Use the Send Test button on any endpoint to fire a form.test event immediately. This verifies your endpoint and signature verification are working before you go live.