> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usepatchwork.co/llms.txt
> Use this file to discover all available pages before exploring further.

# The Webhook endpoint object

> A URL in your infrastructure that receives events, with its own signing secret and its own view of which traffic it covers.

Registered under **Settings → Webhooks**. An endpoint is a subscription: it names the events it wants and, optionally, narrows them to part of your traffic.

<ResponseField name="url" type="string" required>
  Where deliveries are POSTed. Must be https, and must answer within 8 seconds.
</ResponseField>

<ResponseField name="description" type="string">
  Yours, so a list of endpoints stays readable.
</ResponseField>

<ResponseField name="secret" type="string">
  Keys the signature on every delivery. Distinct from your workspace request secret. Returned only to workspace owners.
</ResponseField>

<ResponseField name="events" type="string[]" required>
  Which types to deliver, drawn from the catalogue below. Required — there is no default, so a type added to the catalogue later never starts arriving here. `run.*` expands when you save it.
</ResponseField>

<ResponseField name="origins" type="string[]" required>
  Which surfaces to accept: `agent`, `api`, `mcp`, `console`, `playground`. Defaults to everything except `playground`, so test messages never reach a production server.
</ResponseField>

<ResponseField name="connection_ids" type="string[]">
  Only runs that talked to these [connections](/api-reference/connection). Empty means every connection. A run whose agent uses no connection is not covered by a connection filter.
</ResponseField>

<ResponseField name="agent_keys" type="string[]">
  Only runs of these agents, by key, so a filter survives publishing a new version. Empty means every agent.
</ResponseField>

<ResponseField name="payload" type="string">
  `full` or `thin`. `thin` omits `data`, leaving the ids and a reason to read the resource back.
</ResponseField>

<ResponseField name="active" type="boolean" required>
  An inactive endpoint is skipped without error.
</ResponseField>

<ResponseField name="disabled_reason" type="string">
  Why we switched it off, when we did.
</ResponseField>

<ResponseField name="rotated_until" type="string">
  While a rotation is in its overlap window, when the previous secret stops signing.
</ResponseField>

<ResponseField name="last_delivered_at" type="string">
  Timestamp of the last successful delivery.
</ResponseField>

## The catalogue

```
run.started · run.completed · run.failed
elicitation.requested · action.proposed · write.confirmation_requested · handoff.requested
message.completed
tool_call.started · tool_call.completed · plan.updated
extract.completed · extract.failed
```

`message.delta` and `message.block` are realtime-only. Requesting a type outside the catalogue is rejected rather than ignored.

## Delivery

Each delivery is a POST carrying the full [event](/api-reference/event) as its body, with three headers:

| Header | Value |
| - | - |
| `Patchwork-Signature` | `t=<unix>,v2=<hmac-sha256>` — possibly more than one `v2` |
| `Patchwork-Event` | The event type. |
| `Patchwork-Delivery` | The event id. |

Verify with **this endpoint's secret**, using the scheme in [Signing and verification](/guides/signing), accepting if any `v2` matches and rejecting a timestamp more than five minutes old.

## Retries

Anything `300` or above is a failure, and redirects are not followed. Failures retry immediately, then after 30s, 2m, 10m, 1h and 6h — six attempts over about eight hours — then stop.

`410 Gone` is treated as "stop sending": the endpoint is switched off straight away with no retry.

Deliveries are not ordered, and a retry can land after a later event. Deduplicate on `Patchwork-Delivery` and treat each event as a statement about a run you can re-fetch, not as a state machine of its own.

See [Events and webhooks](/guides/events) for the delivery log, replay, test events and secret rotation.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.