Send events to your own systems with outgoing webhooks

A webhook lets SrvYard tell your own software that something happened. When a deployment finishes, a certificate is renewed or a monitor goes into alert, SrvYard sends an HTTPS request with a JSON description to an address you chose. Your release board, your chat bot, your incident tool or a small script can react to it.

This article shows how to add a webhook, what a delivery looks like and how to verify that it really came from SrvYard, how to read the delivery history, and what happens when your endpoint is down. If you want messages in a chat app rather than JSON for a program, use Slack and Discord notifications.

Before you begin#

• A plan with webhooks. Webhooks are included in Pro and Business. On Hobby the page says "Webhooks are not in your plan". See Plans and limits compared.
• Permission. Seeing webhooks needs webhooks:view (owners, admins and managers). Creating, changing, rotating and deleting them needs webhooks:manage, which owners and admins have.
• An HTTPS endpoint that answers quickly. The address must start with https://. Addresses on private or internal networks are refused, redirects are not followed, and the address itself is stored encrypted.
• A limit to know about. An organisation can have 20 webhooks.

1. Open Webhooks#

Choose Settings in the sidebar, then Webhooks. The page explains itself: "Send events from this organisation to your own systems as signed JSON. Pick the events each webhook hears and verify every delivery with its secret."

1. Verify signatures. Opens a reference panel for the person who writes the receiving code (step 3).
2. Add webhook. Creates a webhook (step 2).
3. Status. Active, or Switched off. Hover over a switched-off webhook to read why it was switched off.

The table also lists the Endpoint (the host name of the address), the Events it hears (All events or a count), the Last 24 hours (how many deliveries succeeded and failed), the Last delivery time and the start of the Secret.

2. Add a webhook#

Press Add webhook.

1. Name. A label, such as Release tracker.
2. Endpoint URL. "https only. Addresses that resolve to private or internal networks are refused. Redirects are not followed. The address is stored encrypted."
3. Events. All events includes events added in the future. Switch it off to tick groups and single events, just as for a notification channel: Servers, Sites, Deployments, Certificates and domains, Backups and snapshots, Monitoring, Databases, Recipes and imports, and Team and access. Each event has a key such as deployment.finished that appears in the delivery.

There is also an optional Description. Press Add webhook. SrvYard then shows the signing secret, which starts with whsec_. Copy it now: it is shown only this once. Later the table shows only the first and last few characters.

3. Know what a delivery looks like#

Each delivery is a POST with a JSON body. Press Verify signatures to see the details on the page itself.

1. Request. The headers: User-Agent: SrvYard-Webhooks/1, X-SrvYard-Event (the event key), X-SrvYard-Delivery (the id of this delivery, new for a redelivery), X-SrvYard-Timestamp (Unix seconds) and X-SrvYard-Signature. Under them is an example body. It has an id such as evt_..., the event type, created_at, the organization (id and handle) and data with the server, site and deployment that the event concerns. Passwords, tokens and environment values are never included.

Further down the panel has the code to check the signature.

Verify the signature has tabs with working code in PHP, Node.js and curl / openssl. The signature header looks like t=1700000000,v1=<hex>. To check it, compute an HMAC-SHA256 of the timestamp, a dot and the raw body, with your secret as the key, and compare it with every v1 value in constant time. Under Replay protection the panel adds: reject a delivery whose timestamp is more than five minutes from your clock, and remember the ids of events you have handled.

Retries and redeliveries of an event carry the same event id, so remembering which ids you have handled keeps you from processing one twice.

4. Read the delivery history#

Open Deliveries from the row menu, or press the webhook's name.

1. Send test event. Sends a webhook.test event so you can check your endpoint without waiting for something to happen.
2. A failed delivery. The columns are Time, Event, Status, HTTP (the answer code), Duration and Attempts. "3/8" means the third of at most eight attempts. The statuses are Delivered, Retrying, Failed, Abandoned and Pending. Deliveries are kept for 30 days.

Press a delivery to see it in detail.

1. Redeliver. Sends the same event again as a new delivery (with a new delivery id and the same event id). Use it after you fixed your endpoint.
2. Request headers, Request body and Response body (first 2 KB) show exactly what went out and what your server answered, which is usually all you need to find a bug.

5. Retries and automatic switch-off#

SrvYard expects any 2xx answer within 10 seconds.

• Retried. A timeout, a 5xx, a 408 or a 429 is tried again, up to seven more times: after 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours, 12 hours and 24 hours. A Retry-After header on a 429 is respected.
• Not retried. Any other 4xx, such as 400 or 404, counts as a failure at once: a retry would get the same answer.
• Switched off. A webhook that keeps failing is switched off so that it does not fill up. After ten failed deliveries in a row, the first of them at least three days old, SrvYard marks it Switched off, and the owners and admins are told by email and in the app. Switch on in the row menu starts it again and resets the counters.

6. Switch off, rotate the secret or delete#

The three-dot menu of a row has the other jobs.

1. Deliveries. The history of that webhook.
2. Send test event. The same as the button in the history.
3. Rotate secret. Creates a new secret and shows it once. The old secret keeps working for 24 hours, and during that time every delivery carries two v1= values in the signature header, so your receiver accepts either. This gives you a day to update the secret on your side without dropping events.

The menu also has Edit, Switch off (or Switch on) and Delete. Deleting asks you to type the webhook's name.

Troubleshooting#

• "Webhooks are not in your plan". Upgrade to Pro or Business: see Plans and limits compared.
• The address is refused when I save it. It must be https, must not point at a private network or an internal host name, and must not contain a user name or password.
• My receiver says the signature is wrong. Use the raw request body, not a re-encoded one, and put the timestamp, a dot and the body together before hashing. Check that you use the right secret, the one for this webhook.
• Deliveries show Retrying forever. Your endpoint answers with an error or too slowly. Look at the Response body in the delivery and your own logs.
• I did not receive an event I expected. Check the webhook's Events, and that the webhook is Active. A webhook switched off hears nothing.
• I need the same events as email. Use a notification channel for that.

Related#

• Slack and Discord notifications: messages for people instead of JSON for programs.
• Event payloads and signatures: the full list of events and their payloads.
• Notification channels: the same events by email, Slack, Discord and Telegram.
• Create an API token and pick scopes: manage webhooks from scripts instead.