11.1Set up a webhook channel

First, build an endpoint on your server. It must accept POST requests with a JSON body and reply with a 2xx status (any HTTP status from 200 to 299). Then add the channel in obsrvly.

In the dashboard#

Select alerting, then channels.
Select + new channel. If you have no channels yet, select + add a channel.
In New alert channel, select the Webhook tile.
Fill in the fields in the table below.
Select Create channel. The button works only when Name and an https:// Webhook URL are filled in.

Field	What to enter
Name	Required. A name to find the channel later, such as `ops-team`.
Webhook URL	Required. The `https://` address of your endpoint, such as `https://your.app/alerts`. Enter the final address, not one that redirects.
HMAC signing secret	Optional, but recommended. A long random string that only you and obsrvly know. When set, every request carries an `X-Obsrvly-Signature` header (11.4). obsrvly uses the secret exactly as you type it, including spaces.
Headers	Optional. Extra headers sent with every request, such as `Authorization: Bearer …`. Select Add header for each one. Rows with an empty name are dropped.

Attach the channel to monitors#

A channel gets alerts only from the monitors it is attached to. Attach it in either place:

On the channel: open it in alerting → channels. Under pages these monitors, select each monitor name to attach it or detach it.
On a monitor: use the on failure — notify picker in the monitor's settings.

If you attach the channel to a monitor that is already down, obsrvly sends the open incident's alert.fire to the new channel, unless the monitor is muted.

Send a test#

Open the channel in alerting → channels.
Select send test. obsrvly sends a real request to your URL.
Read the result: ✓ test sent, ✗ test failed with the error, or test limit reached.

The test uses the saved settings. Select save channel before you test a change.
The test is an alert.fire (11.3). Its alert_id starts with test-, monitor_id is empty, and monitor_name is obsrvly test — no monitor is down.
You can send up to 5 tests per channel each minute, and up to 30 per team each hour.
A failed test is not sent again. Fix the problem and test again.

Edit or delete the channel#

Open the channel. Change the url, custom headers or hmac signing secret, then select save channel.
To stop signing, clear the secret box and save.
To delete, select delete channel…, then yes, delete.
You cannot change a channel's type. Add a new channel and delete the old one.

Errors you may see#

The dashboard shows url can't be empty or Must be an https URL. The API returns these messages, after invalid input: :

Message	What to do
`name required`	Enter a name.
`name must not contain control characters`	Remove line breaks and other hidden characters from the name.
`webhook_url required`	Enter a URL.
`webhook_url must be at most 8192 bytes`	Use a shorter URL.
`webhook_url is not a valid URL`	Check the URL for typing errors.
`webhook_url must be an https URL`	Use an address that starts with `https://`.
`webhook_url has no host`	Add the host name, such as `your.app`.
`webhook_url: destination is not a publicly routable address`	The URL must be reachable from the public internet. `localhost` and private network addresses are refused.
`webhook_headers can hold at most 50 headers`	Remove headers. A channel can have up to 50.
`webhook_headers: "<name>" is not a valid header name`	Use letters, digits and dashes, such as `X-Api-Key`.
`webhook_headers: the value of <name> has a character a header cannot carry`	Remove line breaks from the value.
`webhook_headers: <name> is over 8 KiB`	Keep each header's name and value under 8 KiB together.

With the API#

You can also manage webhook channels with an API key (chapter 13). Create a channel with CreateWebhookChannel:

Create a webhook channel

bash

API=https://www.obsrvly.com/api/gw
curl -s $API/monitor/obsrvly.v1.MonitorConfigService/CreateWebhookChannel \
  -H "Authorization: Bearer $OBSRVLY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "ops-team",
       "webhookUrl": "https://your.app/alerts",
       "webhookHeaders": {"Authorization": "Bearer my-token"},
       "webhookSecret": "<a long random string>"}'

The reply holds the new channel in channel. Attach it to monitors with alertChannelIds. On an update, also send replaceAlertChannels: true (3.7).

Change a channel with UpdateAlertChannel. Send its id and only the fields you want to change:

name, webhookUrl: send a new value, or leave the field out to keep it.
webhookSecret: leave it out to keep the secret. Send "" to remove it.
webhookHeaders: used only with replaceWebhookHeaders: true. The list you send then replaces all headers.

Send a test

bash

API=https://www.obsrvly.com/api/gw
curl -s $API/notification/obsrvly.v1.NotificationService/TestChannel \
  -H "Authorization: Bearer $OBSRVLY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"channelId": "<channel-id>"}'

TestChannel replies with status (sent or failed), errorMessage, subject and body. A failed delivery is still a successful call: check status. Delete a channel with DeleteAlertChannel and its id.