Receive messages from your own tools with webhooks

A webhook is an address another program sends messages to. Yardmaster can listen on this computer, so your own scripts, build tools and monitors can drop a note into Yardmaster when something happens. It only receives; it never sends anything back out.

Set up a webhook#

1. 1

   Open Settings > Channels and expand Webhooks.

2. 2

   Turn on Webhook Integration.

3. 3

   In the Port: box, type a number between 1024 and 65535 (for example 9400), then click outside the box to save it.

4. 4

   Quit and reopen Yardmaster. The card now says Running on port and your number.

5. 5

   Under Add Webhook Source, type a name for the sender and a token of at least 32 characters, then click Add Source.

6. 6

   Click the copy button next to the source to copy its address.

7. 7

   Set up your tool to send a POST request to that address, with the header Authorization: Bearer followed by your token.

Click the test button next to a source to send it a test message; OK (200) means it works. Messages appear under Webhooks in the projects column, grouped by source, with the body laid out neatly when it is JSON.

Who can reach it#

The address only works on this computer: it starts with http://localhost. A website or online service elsewhere cannot reach it directly; you would need your own way to forward messages to this computer, which Yardmaster does not set up.

Requests without the right token get Unauthorized and are dropped. Each message can be up to 1 MB, and each source accepts up to 60 messages a minute.

Do something when a message arrives#

New webhook messages can trigger your automations, for example to start an agent when a build fails. Webhook messages also turn up in search.

Remove a source#

Click the remove button next to the source and confirm Remove. Anything still sending to that address stops working. This cannot be undone.

Turn webhooks off#

To stop accepting webhook messages, remove all your sources: requests to a removed source are refused.