switchyard

for agents: this page is markdown at https://switchyard.so/docs/webhooks.md; every page is listed in 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

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.

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, 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:

HeaderContent
webhook-idthe event's id, the same on every attempt
webhook-timestampwhen the request was signed, in seconds since 1970
webhook-signaturev1, 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 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).

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:

{
  "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.typeSent when
workspace.submitteda task is submitted to the merge queue
workspace.mergeda task merged on main; a batch sends one event for each of its tasks
workspace.sent_backthe merge queue sent a task back
change.fixedSwitchyard 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 REST 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