Guide - updated November 2026
How to set up and debug a form webhook
A form webhook is an HTTP request your form backend sends to a URL you control when someone submits a form. Set the receiver to accept a POST, return a 2xx status when it stores the data, and verify the signature on the server before trusting the body.
This guide walks through the request lifecycle, when GET is acceptable, how to validate an endpoint, what each status code means, how to test payload fields, and how to handle secrets without pasting credentials into a page. To inspect a sample body in your browser, open the free webhook tester.
What happens during a form webhook request?
The lifecycle has five steps. A visitor submits the form, the form backend validates and stores the submission, the backend builds a webhook payload, it sends an HTTP request to your receiver, and your receiver returns a status code that tells the sender whether to retry.
- Submit. The browser posts the form fields to the form backend. The backend is the only party that needs the form access key.
- Store and screen. The backend saves the submission and runs its spam checks before any webhook is sent.
- Build the payload. The backend serialises the fields, adds metadata such as a submission ID and timestamp, and signs the body when signing is enabled.
- Deliver. The backend sends a POST request to your receiver URL with a timeout. A slow receiver is treated as a failure even if it eventually finishes.
- Respond. Your receiver verifies the signature, parses the body, stores or routes the data, and returns a status code. A 2xx ends the attempt; a 5xx or timeout may be retried.
For the product side of this flow, see HTML form to webhook and the webhook feature overview.
Should a form webhook use GET or POST?
Use POST for the submission payload. POST carries a request body, keeps field values out of the URL, and matches the semantics of creating a record on the receiver. GET has no body in normal use, so field data would end up in the query string, browser history, proxy logs and referrer headers.
GET is still useful in two narrow cases: a read-only health check that returns whether the receiver is up, and a verification challenge where the provider explicitly asks you to echo a token. Neither case should carry a real submission. If a provider only offers GET for delivery, treat the payload as public and do not put personal data in it.
How do you validate a webhook endpoint?
Validate the endpoint in four passes: reachability, method, payload shape, and failure handling. Send a small test request from the form backend or a tester, confirm the receiver answers with a 2xx, check that the parsed fields match the form, then send a deliberately invalid body and confirm the receiver returns a clear 4xx instead of accepting it.
- Reachability. The URL must be public HTTPS and must not sit behind a login, a bot challenge or a firewall that blocks the sender.
- Method. The route must accept POST. A route that only handles GET returns 405 and the delivery fails.
- Payload shape. Field names, types and nesting must match what the receiver reads. Inspect a sample body in the webhook tester before wiring the live form.
- Failure handling. A missing required field should produce 400 or 422, not a silent 200. A bad signature should produce 401 or 403.
If the form itself submits but the webhook never arrives, work through the form submission troubleshooter to separate a form problem from a delivery problem.
What do webhook status codes mean?
The status code is the receiver's instruction to the sender. A 2xx means the payload was accepted, so the sender should stop. A 4xx means the request itself is wrong and a retry will not help until you fix it. A 5xx means the receiver failed temporarily and a retry may succeed.
| Code | Meaning | What to check |
|---|---|---|
| 200 / 204 | Accepted | Data stored or routed; no retry needed. |
| 202 | Accepted for later | Receiver queued the work; confirm the queue drains. |
| 301 / 308 | Moved permanently | Update the webhook URL to the final HTTPS path. |
| 302 / 307 | Temporary redirect | Point the webhook at the final URL, not a redirect. |
| 400 | Bad request | Malformed JSON or missing required fields. |
| 401 / 403 | Unauthorised / forbidden | Signature, token or IP allowlist is wrong. |
| 404 | Not found | Route path is wrong or the receiver is not deployed. |
| 405 | Method not allowed | Route does not accept POST. |
| 408 | Request timeout | Receiver is too slow; respond before the sender times out. |
| 413 | Payload too large | Body or file field exceeds the receiver limit. |
| 415 | Unsupported media type | Content-Type does not match the parser. |
| 422 | Unprocessable content | JSON is valid but a field value fails validation. |
| 429 | Too many requests | Rate limit hit; slow the sender or raise the limit. |
| 500 / 502 / 503 / 504 | Server error | Receiver crashed, upstream failed or timed out; retry later. |
How do you test webhook payload fields?
Test with fake values and a body that matches the real shape. Use something like test@example.com, a short sample message, and a made-up name. Never use a real customer record, a live access key or a production secret in a test payload.
- Capture one sample. Send a test submission and copy the raw body from the receiver log or the form backend.
- Inspect the structure. Paste the body into a webhook tester to see the parsed fields, types and nesting.
- Compare with the receiver. Check that every field the receiver reads exists and has the expected type. A number sent as a string is a common cause of a 422.
- Test the edges. Send an empty optional field, a long message and a missing required field. Confirm each produces the response you expect.
- Replay after a fix. Send the same body again and confirm the receiver now returns 2xx and stores the record once.
How should you handle webhook secrets safely?
Keep the signing secret or token on the server, in an environment variable that only the receiver can read. Verify the signature before parsing or trusting the body, and reject a request whose signature is missing or does not match. Never put a secret in client-side JavaScript, a public repository, a screenshot or a support ticket.
- Store it server-side. Use the hosting provider's environment variables or secret manager, not a committed file.
- Compare in constant time. Use the platform's timing-safe comparison helper rather than a plain string equality check.
- Rotate after exposure. If a secret may have leaked, create a new one in the provider dashboard, update the receiver, and confirm old signatures are rejected.
- Do not ask visitors for credentials. A guide or tester should never request a real access key, password or signing secret. Use fake values and keep the real ones in your own environment.
To inspect a sample payload without exposing a real secret, use the browser-based webhook tester. It parses the body locally, so there is nothing to install and no credential to enter.
Frequently asked questions
What is a form webhook?
A form webhook is an HTTP request that a form backend sends to a URL you control when a submission arrives. Instead of only emailing you, the backend posts the submission data as JSON or form-encoded fields to your endpoint, so another system can store it, route it, or trigger an action.
Should a form webhook use GET or POST?
Use POST for form submissions. A webhook carries a body of field data, and POST is the method designed to send a body without putting it in the URL. GET is only appropriate for a read-only health check or a verification challenge that the receiver expects, never for the submission payload itself.
How do I validate a webhook endpoint before going live?
Send a small test payload from the form backend or a webhook tester, confirm the receiver returns a 2xx status, and check that the parsed fields match what the form sends. Then test a failure case, such as a missing required field, and confirm the receiver rejects it with a clear 4xx response instead of silently accepting it.
Which HTTP status code should a webhook receiver return?
Return 200 or 204 when the payload is accepted and processed. Use 400 or 422 for malformed or invalid fields, 401 or 403 when the signature or token is wrong, 404 when the route does not exist, 405 when the method is wrong, 429 when the sender is rate limited, and 5xx only when your own receiver has a temporary failure. A 2xx tells the sender to stop retrying.
How do I test webhook payload fields safely?
Use fake values such as test@example.com and a short sample message, never a real customer record. Paste the sample body into a webhook tester to inspect the parsed structure, then compare the field names and types with what your receiver expects. Keep the test payload in a scratch file or the tester, not in a public page or screenshot.
How should I handle webhook secrets?
Keep the signing secret or token in the receiver's server-side environment variables, never in client-side JavaScript, a public repository, or a screenshot. Verify the signature on the server before trusting the body. If a secret may have leaked, rotate it in the provider dashboard and update the receiver, then confirm old signatures are rejected.
Why does my webhook work in a tester but fail in production?
The most common causes are a different URL or path in production, a firewall or bot rule blocking the sender, a missing signature header, a timeout on a slow receiver, or a response body that is not valid JSON. Compare the production request headers and status code with the tester request, then check the receiver logs for the same timestamp.
Set up your first form webhook
Connect an HTML form to a signed webhook, or inspect a sample payload before you wire the live receiver.
Set up form to webhookOpen the webhook tester