Webhook onboarding: show what happened after the test event arrived
A webhook test needs separate receipts for delivery and the resulting application action. Design setup states that make the first useful event understandable.
In this article
“Webhook connected” can describe a saved address, a delivered request or a completed action in the receiving application. Those are different achievements. A useful setup flow tells the developer which one it has actually observed and what to check next.
Stripe’s webhook documentation makes the distinction concrete. A successful HTTP response signals delivery to the endpoint, while Stripe recommends responding before complex processing that could cause a timeout. The response can therefore precede the work the customer cares about.
For onboarding, the completion criterion should follow the intended action far enough to make that difference visible. If the webhook is meant to create a task, the first meaningful result is a recognizable test task in the intended destination. A green delivery receipt is part of the route toward it.
Name the four states separately
A product can explain the journey with four plain-language states: destination saved, test event sent, destination acknowledged and intended action confirmed. These are proposed interface labels, not a claim that every webhook provider exposes this exact sequence.
“Destination saved” means the configuration exists. It should display the endpoint and environment so the developer can notice an accidental test/live mismatch. It does not imply that the URL is reachable or that its handler understands the selected event.
“Test event sent” should identify the event and send attempt. If the product has only queued the request, say queued. The distinction matters when the user refreshes and wonders whether to send another one.
“Destination acknowledged” means the sender received the expected response. Show the response and the delivery timestamp where available. Keep the visible explanation narrow enough that a developer does not mistake a server acknowledgment for proof that a queued job has finished.
“Intended action confirmed” needs its own observation. The receiving application may report a result identifier back to the setup screen. Otherwise, give the developer a clear manual check: open the destination and find the sample record. If the product cannot inspect that application, label the final state as user-confirmed rather than automatically verified.
Use one identifiable test object
Consider an illustrative work-management integration. When a fictional order is marked ready, the webhook should create a dispatch task in a test workspace. No order is shipped and no live automation is executed in this example.
The setup screen chooses one clearly marked test order and shows the destination workspace before sending. The expected task title includes a distinctive sample label. After delivery, the receipt links the originating event to the resulting task ID, if the receiver supplies one.
That connection is useful when something goes wrong. A developer can ask whether this particular event produced this particular task. Without it, the presence of any task in the workspace can be mistaken for success, especially when a teammate has been testing the integration too.
The first receipt might read: “Test event acknowledged. Check the Dispatch Test workspace for the sample task.” Once the application reports the task ID, it can become: “Sample task created in Dispatch Test.” If a person performs the check instead, the interface should retain that distinction.
A second screenshot of a green checkmark would add little to this journey. A direct path to the actual result adds much more.
Make replay an explicit experiment
A replay button should tell the developer whether it resends the same event or creates a new example event. Those actions test different things.
Stripe documents that duplicate deliveries can occur and recommends tracking processed event IDs. Its CLI documentation also explains that triggering example events creates underlying API objects, and one trigger may produce related events. A new generated example is therefore not interchangeable with resending an existing delivery.
For the fictional dispatch integration, propose two separate checks. First, resend the same test event and inspect whether the same dispatch task remains the only task associated with it. Second, create a distinct test order and verify that it produces its own task. Label both as test-workspace actions and show what each may change.
The desired behavior depends on the integration’s contract. A task-creation handler should generally avoid duplicate task creation for a repeated delivery of the same event; another handler may update an existing record. State the expected effect before the user presses replay, then compare the result with that expectation.
Do not let cleanup erase the diagnostic trail immediately. The developer may need the event ID, result ID and delivery attempts to understand why two tasks appeared. Offer cleanup after the relationship between them is clear.
Give each failure an owner
An endpoint that never acknowledges the event requires a different investigation from a receiver that acknowledges it and then fails to create the task. The setup flow should route those failures accordingly.
For delivery failures, show the destination, environment, attempt time and returned status or connection error. Give the developer a way to confirm the URL and consult the provider’s relevant delivery documentation.
For processing failures, preserve the successful delivery receipt and expose the receiving application’s result or error where available. Rewriting the entire journey as “Connection failed” discards the most useful information: the sender has already reached the receiver.
For an action that remains pending, say which system owns the next step. If the receiver processes work asynchronously, include a result-status link or a manual destination check. A continually spinning button makes it difficult to tell whether another send would help or create more work.
Avoid universal retry promises. Provider behavior varies by environment and configuration. The setup screen should show the current provider’s actual next retry, when available, or link to its documented behavior without inventing a countdown.
Review the result outside the happy path
Before releasing the onboarding flow, run a controlled internal review with a handler that acknowledges before completing its work. This is a proposed acceptance exercise. It should demonstrate that the UI can hold “delivered” and “still processing” at the same time.
Then test an acknowledged event whose downstream action fails, a repeated delivery and a result created in the wrong test workspace. The point is to see whether the person can locate the break without starting the entire setup again.
Keep the acceptance notes specific: which state appeared, which identifier was available, what the developer checked and whether the next action was clear. These observations are more useful than a single “integration successful” checkbox.
A first webhook journey is finished when the developer understands the relationship between an event and its intended result. The same distinction will make later troubleshooting easier, because the product has already taught them what each receipt proves.
