Practical guide
Separate a Webhook Intention From Delivery
A webhook line in a survey file can look like a connection. It may name an event and a destination. Nothing has crossed the network.
That gap matters the moment another system depends on the response. A stored description can help you plan delivery. It cannot prove that a sender made a request, the destination answered, a retry occurred, or a failed attempt was recorded.
Start with the object you have
The file-based survey example creates a delivery description after a response is complete. The description contains four useful facts:
- the event that would cause delivery;
- a label for the intended destination;
- a digest that identifies the completed payload;
- the time the description was created.
It also says the payload was planned and not sent. There is no destination URL in the object and no network sender behind it.
This is useful planning material. You can check whether the event name makes sense, whether the destination label points to the right purpose, and whether the description belongs to the completed response under review.
It is not delivery evidence.
Use five records to test a webhook claim
When someone says a webhook is working, ask for five distinct records.
1. Description
What should trigger the handoff? Where should the data go? Which payload does the description identify?
The file example answers these planning questions. It stops here.
2. Request
Did a sender transmit data to a specific network address? A delivery record should identify the destination, request method, time, and payload identity without revealing credentials.
Typeform documents this transport as a JSON payload sent by HTTPS POST to a configured destination. That vendor behavior is separate from the file example.
3. Acknowledgement
What did the destination return? Typeform instructs receiving endpoints to return a 2XX HTTP response to confirm successful delivery. Its documentation treats any other response, or no response, as a failed delivery.
The file example receives no HTTP response because it sends no request.
4. Retry
What happens after an unsuccessful attempt? A real delivery system needs a stated rule for whether another request occurs and when it stops.
Typeform documents retry behavior for failed webhook requests. The file example has no retry mechanism because there was no first attempt.
5. Failure record
Can you inspect what was sent, what came back, and how the attempt ended? Typeform’s workspace webhook flow lets users view request and response details for recent deliveries.
The file example creates no delivery history. Calling its description a failure record would be as inaccurate as calling it a success record.
The proof is the empty side of the comparison
Put the five records on one page. Mark what you can inspect.
- Description: present.
- Network request: absent.
- Acknowledgement: absent.
- Retry: absent.
- Failure record: absent.
That pattern does not mean the description is broken. It means the job ends before transport begins.
The boundary protects both decisions. A person who needs planning evidence can use the smaller object without pretending to run an integration. A person who needs delivery can reject it before a missing response causes downstream confusion.
When the smaller job fits
Use a stored delivery description when you are reviewing a survey design before transport exists. It can help a developer, analyst, or project owner agree on the event, intended destination, and payload identity.
Choose a delivery system when another application must receive the response. That job needs a sender, a network destination, acknowledgement handling, retry rules, and inspectable attempt history.
Do not transfer Typeform’s delivery behavior to a file because both use webhook language. The vendor service sends requests and evaluates responses. The bounded file job records what a later sender could use.
Audit the next webhook claim
Take one webhook description and label it either planning evidence or delivery evidence. If you need delivery, require all four missing records before relying on it: request, acknowledgement, retry, and failure history.