Oliver starts booking a bike on the rental shop's site and leaves before paying. The site tells Heythere, and the shop's automation writes to him on WhatsApp. The site reaches Heythere through a webhook source: an address of the workspace that another service posts events to, such as your site when a booking is left unfinished, or Stripe when a deposit is paid. Its requests start runs through webhook.received triggers, and resume runs that wait at a wait step of type webhook.
An agent creates one with saveWebhookSource, which returns its url. The member pastes it where the service sends webhooks.
How does Heythere know a request comes from that service?
Anyone could post to that address, so each source checks the signature the service puts on every request, with a signing secret the member saves as a workspace secret. Its verification says how the service signs: Stripe's Stripe-Signature header, an HMAC of the body as GitHub or Shopify send it, the Standard Webhooks headers, or a token in a header. A request that fails the check is refused, and the source keeps the latest refusal and its reason in lastRefusal.
How does a request reach a contact or a run?
A
webhook.receivedtrigger reads the contact's phone number atcontactPhoneNumberPath, so the site sends Oliver's number with the booking. It starts a run for a contact the workspace knows, opening their conversation with the automation's number if they never wrote to it, unless a run, a live chat or a handover holds it. Its run sends only templates, each one the contact's consent allows.A
waitstep of typewebhookwaits for a request that names its run. The automation sends Oliver a Stripe Payment Link for his deposit, with{{run.id}}as itsclient_reference_id, and Stripe sends it back at the source'srunIdPathonce he pays. The step saves the request's values and goes on to confirm his booking, or takes its timeout. A request that comes before the run reaches the step resumes nothing.
A request whose event key, read at eventKeyPath, came before is not handled again, so a service retrying a delivery starts nothing twice.
Where to look when nothing happens?
Oliver left his booking and got no message? listWebhookSourceEvents lists the requests the source accepted in the last 30 days, with their body and what each trigger or run did with them, such as contact_unknown when the workspace does not know his number, or run_active. A request refused before it was kept shows only in lastRefusal.
In the API
Every operation is a REST endpoint and, unless marked REST only, an MCP tool of the same name. The OpenAPI document describes their parameters, payloads, and errors.
- PUT
saveWebhookSourceSave a webhook source
/api/organizations/{organizationId}/workspaces/{workspaceId}/webhook-sources/{name} - GET
listWorkspaceWebhookSourcesList webhook sources
/api/organizations/{organizationId}/workspaces/{workspaceId}/webhook-sources - GET
listWebhookSourceEventsList the requests of a webhook source
/api/organizations/{organizationId}/workspaces/{workspaceId}/webhook-sources/{name}/events - DELETE
deleteWebhookSourceDelete a webhook source
/api/organizations/{organizationId}/workspaces/{workspaceId}/webhook-sources/{name}