Browse the docs

POST /hooks/{name}

Fires every macro with a webhook trigger on that route, with the JSON body and query items as inputs.

Details #

A macro listens on a route with the webhook trigger. Send a POST (or a GET, when the trigger allows it) to /hooks/<route> and each macro that listens there runs. By default the response is 202 with the run ids; a trigger can ask to wait for the macro and answer with a Reply to webhook step. The route may contain slashes (/hooks/github/push).

Show a deploy request
When
  1. A webhook is called at /deploy
Do
  1. Show “Deploy {{env}} requested”
Open in Switchboard to try it
curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  -d '{"env":"staging"}' "http://127.0.0.1:48080/hooks/deploy?by=ci"
{ "runIds": ["r_a77b10"] }

Inputs the macro sees:

  • webhook: {method, route, query, headers, body, json?, form?, text?, contentType, remote}.

  • Each top-level key of a JSON object body.

  • Each query item, as text (a repeated name is a list). A query item wins over a body key with the same name.

  • body: the raw body as text, whenever the body is not empty.

Parameters #

curl --unix-socket "$SWITCHBOARD_HOME/engine.sock" -X POST http://localhost/hooks/{name}

Fire the macros with a webhook trigger on that route. The Unix socket needs no token; loopback 127.0.0.1:48080 needs Authorization: Bearer <api-token>.

Gotchas #

  • 401 without credentials the route accepts (the bearer token, the route's key, or a valid signature, depending on the trigger's auth). Once signed in, an unknown route is 404 with no macro listens to /hooks/<name>.

  • 405 with an Allow header for a method the route does not take; 400 for an invalid JSON body; 409 when the macro is busy and set to ignore overlapping runs; 413 over 10 MB; 429 with Retry-After over the rate limit (30 a minute by default).

  • On the Unix socket no auth is needed, which is how switchboard hook calls.

  • Disabled macros and macros held back by scope or conditions do not run, and are listed by GET /not-fired.

See also #