Webhooks
A webhook Service receives an HTTP request from another system and runs your code for that event. Tokay gives it a stable endpoint and records each request so you can tell whether the sender connected, what payload arrived, and how the code responded.
Last updated
AI agent? Start with llms.txt.
The code can be a server that listens for requests or a handler function that accepts one request. Tokay detects the shape and runs it as a webhook Service.
Give the sender the Service URL
Each webhook gets a URL such as https://fn-x7k2m9q4.tokay.app. Copy it from the Service page into Stripe, GitHub, a form provider, or the system sending events.
The random address is intentionally difficult to guess. Use Regenerate URL when the address is exposed or an integration should lose access. The old URL stops working immediately, so update every sender that should continue calling the Service.
Verify the connection before relying on it
Before any request arrives, the Service page shows Listening for first request.... A successful first request changes the state to Connection Established! and identifies the detected sender when possible.
When the first request reaches the Service but the code fails, Tokay separates that from a sender that never connected and points to the failure evidence.
Use Send test event to test the deployed code before configuring the real sender.
Request history preserves the event that matters
The Requests tab shows the source, HTTP method, response status, duration, and body preview for each incoming request. Expand a row to inspect the full payload.
Copy as cURL creates a command that replays the recorded request. After fixing the code, send the same payload again and confirm the handler now succeeds.
History is limited by request count rather than age, so a low volume integration keeps useful earlier events.
Alerts find you when delivery starts failing
Tokay emails each Owner of the Workspace when the function fails most of its requests for five minutes in a row, and again once it has recovered. A request fails when it returns a 5xx error or gets no answer. A 4xx response is your code rejecting the request, so a provider's occasional bad payload never sends an alert. See Logs and debugging for the timing.
A red 5xx response usually means the handler crashed. The Logs tab contains the application output. An orange 4xx response means the code rejected the request, and the recorded payload shows what the sender supplied.
Respond within five minutes
A webhook must start its response within 300 seconds, or the sender receives 504 Gateway Timeout. Most providers expect a fast reply anyway, so acknowledge the event and hand slow work to a background worker.
Choose who can call the webhook
Most webhook providers need anonymous access. Set the function to Public beside its Service URL, then verify the provider's signature or authentication in your code.
A function called only by systems you control can be Private. Add each caller's Machine identity directly or through a Group. When a webhook route is part of a Private web app, a public route can open that method and path without exposing the rest of the Service.