> Every page of the Heythere docs is listed in https://heythere.io/docs/llms.txt: fetch it to find a page instead of guessing its URL.

# Webhook sources: start automations from Stripe or your site

> Let Stripe, your booking site or any other service tell an automation that something happened, so it writes to a customer or a waiting run goes on.

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](https://heythere.io/docs/concepts/runs) through `webhook.received` [triggers](https://heythere.io/docs/concepts/triggers), and resume runs that wait at a `wait` [step](https://heythere.io/docs/concepts/steps) 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](https://heythere.io/docs/concepts/secrets). 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.received` trigger reads the contact's phone number at `contactPhoneNumberPath`, 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](https://heythere.io/docs/concepts/live-chats) or a handover holds it. Its run sends only [templates](https://heythere.io/docs/concepts/message-templates), each one the contact's consent allows.
- A `wait` step of type `webhook` waits for a request that names its run. The automation sends Oliver a Stripe Payment Link for his deposit, with `{{run.id}}` as its `client_reference_id`, and Stripe sends it back at the source's `runIdPath` once 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](https://app.heythere.io/api/openapi.json) describes their parameters, payloads, and errors.


- `saveWebhookSource`: Save a webhook source. `PUT /api/organizations/{organizationId}/workspaces/{workspaceId}/webhook-sources/{name}`
- `listWorkspaceWebhookSources`: List webhook sources. `GET /api/organizations/{organizationId}/workspaces/{workspaceId}/webhook-sources`
- `listWebhookSourceEvents`: List the requests of a webhook source. `GET /api/organizations/{organizationId}/workspaces/{workspaceId}/webhook-sources/{name}/events`
- `deleteWebhookSource`: Delete a webhook source. `DELETE /api/organizations/{organizationId}/workspaces/{workspaceId}/webhook-sources/{name}`
