Forms · Glossary

What is a webhook? Explained with a form submission

A webhook is an automatic message one system sends to a web address you choose the moment something happens, such as a form being submitted. The message is usually an HTTP POST carrying the details as JSON. Instead of repeatedly asking a service whether anything is new, your system is told as soon as it is.

Webhooks are how a form stops being a list somebody checks and becomes part of a system that acts on each entry. They are simple to set up and easy to get subtly wrong, because the sending side decides what happens when your end is slow or offline.

Indunil Asanka · Co-founder

5 min read · Published 13 September 2026

Webhook, API request or email alert
Question	Webhook	API request	Email alert
Who starts it	The sending system, when the event happens	Your system, whenever it asks	The sending system, to an inbox
How quickly you know	Seconds after the event	As often as you ask	Seconds, then it waits for a person
Read by	Software	Software	People
If your end is down	Depends on the sender's retry policy	You catch up on the next request	The message waits in the inbox
What you need	A public URL that accepts POST	Credentials and code that asks	An email address
Good for	Pushing each new record into another system	Bulk reads and filling in history	Telling a person something arrived

How a delivery works

Somebody submits a form. The form service builds a small JSON document describing the event, opens a connection to the address you registered and posts the document to it. Your endpoint reads the body, replies with a success status, and the exchange is over. Developer documentation for webhooks puts the contrast neatly: webhooks deliver data as it happens, as opposed to polling an API intermittently to see whether anything is new, and you only register interest in an event once. The reply matters more than it looks. Payment platform documentation is emphatic that an endpoint should return a success code quickly, before any complex work, because a slow reply is treated as a failure even when the processing eventually succeeds.

Failures, retries and duplicates

Every sender makes its own promise about what happens when a delivery fails, and it is the first thing to find out. Some retry for days with growing gaps between attempts; others make exactly one attempt and move on. The two need opposite designs. With retries, your endpoint will sometimes receive the same event twice, so it should record an event or record identifier and ignore repeats. With a single attempt, a few minutes of downtime means lost deliveries, so the receiver should accept the post, put the work on its own queue and return at once, and you need another way to catch up, such as an export, when something is missed. Deliveries can also arrive out of order when several events happen close together, so a receiver that depends on sequence should compare timestamps or identifiers rather than assume the latest delivery describes the latest event.

Securing both ends

On the receiving side, anybody who learns the URL can post to it, so the question is how you know a delivery is genuine. Many senders sign each delivery with a secret shared only with you, usually an HMAC of the body placed in a header, sometimes with a timestamp so an old delivery cannot be replayed. When a sender offers no signature, treat the URL itself as a secret, use HTTPS, and check that the payload names a form you actually own. On the sending side, a service that posts to addresses its users type in must not be tricked into reaching private systems. The OWASP guidance on server side request forgery lists webhooks as a classic risk and recommends resolving the host and rejecting private addresses, and disabling redirect following.

What a form submission webhook carries

Most form webhooks send the same few things: an event name so the receiver knows what happened, a timestamp, which form it came from, and the answers. The answers are the part that varies. Some tools key them by the question text, which is easy for a person to read in a log, and some by an internal field identifier, which does not change when somebody edits a label. A few send both, and the difference decides how fragile the automation on the other end will be. A response identifier is the other field worth keeping on the receiving side, because it is what lets somebody match a record in another system back to the original row in the form's responses when the two ever disagree.

The webhook add-on in the form builder

Webhooks are one of the four add-ons, alongside e-signing, email alerts and redirect. Each submission is posted once as JSON, with no retry, to the URL you set. The body has an event of form_submission, a timestamp, a form object with its id, title and slug, and a response object with its id, a data map keyed by field label and a raw_data map keyed by field id. The only header is a JSON content type; there is no signature header, so keep the URL private. The submission is stored in the responses table whether or not the delivery succeeds.

Questions people ask

Is a webhook the same thing as an API?

A webhook is a kind of API call made in the opposite direction. With an ordinary API your program asks another service for data; with a webhook the other service calls your program when there is something to tell it. Many integrations use both: a webhook to learn that something happened, and an API request to fetch any detail the webhook did not include.

Do I need to write code to receive a webhook?

Not necessarily. Automation platforms provide a URL that accepts webhooks and lets you map the fields into a spreadsheet, a CRM or a chat message without code. Code becomes worth it when volumes are high, when the data needs checking before it is stored, or when a missed delivery would be expensive enough to need a queue and monitoring.

What status code should the endpoint return?

A 2xx code, as soon as the delivery has been accepted. Return it before doing slow work such as calling other services, and do that work afterwards. Redirects, errors and slow replies are all treated as failures by most senders. If the payload is malformed, a 400 tells anyone reading the sender's logs that the problem was the data rather than your server.

How do I test a webhook before going live?

Point it at a request inspection service or a temporary tunnel to your own machine, submit the form once, and read exactly what arrives: the headers, the body and the field names. Build your receiver against that real delivery rather than against documentation, then switch the URL to your production endpoint and submit one more test.

Can a webhook carry uploaded files?

Rarely as the file itself. Webhook bodies are text, and senders keep them small, so an upload is usually represented by a reference such as a file name, an identifier or a link that expires. Plan for the receiving system to fetch or copy the file separately, and check how long any link in the payload remains valid.

What if the webhook URL leaks?

Change it. Create a new endpoint address on the receiving side, update the form to use it and switch off the old one, so posts to the leaked address are rejected. Then review what arrived at the old address while it was exposed, since anybody who had it could have sent fake submissions that look genuine.

Make one with forms

The button opens the generator with this use case already described. Change the wording to match your own.

Create a form with OneCraft

Sources

Written and checked by the OneCraft team. Last checked 13 September 2026.