> Switchyard docs. Every page, as markdown, is listed at https://switchyard.so/llms.txt

# Receive webhooks

Receive an HTTPS request from Switchyard when a task is submitted, merged or sent back, or when Switchyard fixes a conflict.

**You will have:** an endpoint that `yard webhook list` shows as `delivering`, and a receiver that checks each request's signature.
**Works with:** the board (project settings), `yard`, MCP, REST.
**Takes:** about 10 minutes.

## Before you start

- You are an admin of the project. On app.switchyard.so, an owner or admin of the organization is an admin of its projects.
- Listing, adding, removing and testing endpoints needs admin access to the project: the project's admin key, an organization API key with admin access, or an admin's sign-in. A task's key cannot do any of them: it is answered 403.
- You have a receiver on a public HTTPS address that can store a secret.

## Step 1 — Add an endpoint

Add the endpoint so that Switchyard sends events to it. The command prints the signing secret one time only, then the result of one test event that Switchyard sends to the new endpoint.

```sh
yard webhook add https://hooks.your-domain.example/switchyard --event workspace.merged --event workspace.sent_back
```

`--event` names one event to send. Repeat it for more events. Leave it out to receive all four events.

```
Output
added webhook <id> for https://hooks.your-domain.example/switchyard: workspace.merged, workspace.sent_back
every delivery is signed with it; its signing secret is shown once:
<signing secret>
test event: delivered, answered 200 in 84 ms
```

Put the signing secret where your receiver reads it. The secret starts with `whsec_`. No command or page shows it again.

The last line is the result of the test event. A receiver that is not ready yet gives `test event: not delivered:` and the reason. The endpoint is added either way. Send another test event when the receiver is ready: `yard webhook test <id>` ([Verify a webhook signature](/docs/verify-webhooks), step 4).

MCP: `yard_webhooks` with `action: "add"` · REST: `POST /v1/projects/<project>/webhooks` with `{ "url": "https://…", "events": [...] }`

The address must use `https` on port 443: leave the port out, or write `:443`. Its host must be a name with a dot, not an IP address, not a local name (such as `localhost` or a `.local` or `.internal` name), and not on Switchyard's own domain. The host's name must resolve in DNS, and every address it resolves to must be public: Switchyard refuses a name that points at a loopback, private or link-local address. The address must not contain a user or a password. A project has at most 5 endpoints.

You have an endpoint. Next, your receiver checks the signature.

## Step 2 — Check the signature

Check the signature so that your receiver acts only on requests from Switchyard. Every request carries three headers, in the Standard Webhooks form:

| Header | Content |
| --- | --- |
| `webhook-id` | the event's id, the same on every attempt |
| `webhook-timestamp` | when the request was signed, in seconds since 1970 |
| `webhook-signature` | `v1,` and then the base64 HMAC-SHA256 of `<webhook-id>.<webhook-timestamp>.<body>` |

The HMAC key is the signing secret without its `whsec_` prefix, base64-decoded. Compute the HMAC over the raw body bytes and compare it with the signature. Refuse a request whose timestamp is more than 5 minutes from your receiver's clock, to stop a replay. A Standard Webhooks library verifies these headers as they are.

[Verify a webhook signature](/docs/verify-webhooks) has a function to copy in TypeScript, Python and Go, and `yard webhook verify`, which says why a request is refused.

Your receiver refuses requests that are not from Switchyard. Next, it answers each request.

## Step 3 — Answer within 10 seconds

Answer each request with a 2xx status within 10 seconds. Switchyard ignores the body of the answer. Any other status, a redirect, or no answer in 10 seconds is a failure, and the event is sent again ([retries and dropping](#retries-and-dropping)).

Switchyard sends each event at least once. A receiver that answered too late can get the same `webhook-id` again. Use `webhook-id` as the key that makes your action happen one time only.

Your receiver answers and acts once per event.

## What arrives

Each request carries one event, as JSON:

```json
{
  "type": "event",
  "id": "evt_4821_0",
  "created_at": "2026-11-03T06:30:12.000Z",
  "data": {
    "type": "workspace.merged",
    "project": "your-project",
    "workspace": "W8",
    "seq": 4821
  }
}
```

| `data.type` | Sent when |
| --- | --- |
| `workspace.submitted` | a task is submitted to the merge queue |
| `workspace.merged` | a task merged on main; a batch sends one event for each of its tasks |
| `workspace.sent_back` | the merge queue sent a task back |
| `change.fixed` | Switchyard fixed a conflict without a person; `data.change` names the change |

`data.workspace` is the task's id: `W8` is task 8. `data.seq` is the event's place in the project's history. The event carries no other facts, so a late or repeated event never carries old facts. Read the current state from the API:

- The task: `GET /v1/projects/<project>/status?workspace=<task>` (`yard status <task>`).
- The history after the event: `GET /v1/projects/<project>/oplog?since=<seq>` (`yard log`).

The [REST API](/docs/api) page lists both routes.

A test event has `data.type` `webhook.test` and no `data.workspace`. Switchyard sends one when you add an endpoint and when you ask for one with `yard webhook test <id>`. An endpoint gets it whatever events it asked for.

## Retries and dropping

Switchyard sends a failed event again after 30 seconds, 2 minutes, 10 minutes and 1 hour, then every 6 hours. Switchyard drops an event when its next attempt falls more than 3 days after the event. At most 1,000 events wait for one endpoint; past that, the oldest is dropped. Waiting events are kept through a restart of the project and are sent when their retry is due.

Switchyard looks up the host's name again before each request, a test event included. When the name resolves to an address that is not public, Switchyard makes no request. The attempt counts as failed with `the address resolves to a private network, so nothing was sent`, and the event is sent again on the same schedule.

Switchyard sends an endpoint only the events it asked for. `yard webhook remove <id>` removes the endpoint and the events that wait for it. It asks first at a terminal; a script adds `--yes`.

## Verify

Run `yard webhook list` after an event. Each line shows the endpoint's id, address and events, and its state:

```
Output
<id>  https://hooks.your-domain.example/switchyard  workspace.merged, workspace.sent_back  delivering
```

`delivering` means no attempt failed since the last answer. A receiver that fails shows `failing N times since it last answered:` and the last error. Dropped events show as `N events given up on`. An endpoint added before the port rule with another port keeps receiving its events, and a `note:` line under it says that an endpoint added today must use port 443. The time of the last delivery is on the project's settings page on the board and in `yard webhook list --json`.

MCP: `yard_webhooks` with `action: "list"` · REST: `GET /v1/projects/<project>/webhooks`

## Next

- [Verify a webhook signature](/docs/verify-webhooks): sample code, `yard webhook verify`, and test events.
- [REST API](/docs/api): the routes to read a task and the history.
- [Fix a conflict](/docs/conflicts): what `change.fixed` means.
