Webhooks
Send events of your project to an https endpoint. Add a webhook, choose its events, send a test event and read its delivery counts.
A webhook is an HTTPS endpoint that receives events from your project. When an event happens, Risicare sends a signed request to the URL of the webhook. You add and manage webhooks on the Webhooks page of the dashboard.
Webhooks are a dashboard feature. An API key cannot manage them.
What runs today: owners and admins add, change, delete and test webhooks on the Webhooks page. Other roles read the list. Each request carries a signature that your receiver checks. See Receive and Verify a Delivery.
What is not available: an API key cannot add, change or delete a webhook in this release. See the REST API reference.
Open the Webhooks page
Click Webhooks in the side navigation. The page shows three counters: Active, Deliveries and Failures. Below them, the card Endpoints lists one row for each webhook. With no webhook, the page says "No webhooks configured".
Add a webhook
Click Add webhook
Only an owner or an admin sees the button. Other roles see "Only an owner or an admin can add, change or delete a webhook." and their role.
Fill in the form
Fill in the fields in the table below. The form shows "Enter a name for the webhook.", "Enter the URL." or "Choose at least one event." when a part is missing.
Click Add webhook
The dialog Webhook created opens.
Copy the secret
The dialog reads "Copy the signing secret of" the webhook "now. You will not be able to see it again." The secret is masked. The eye icon (named Show secret) unmasks it, and the copy icon (named Copy secret) copies it. If the browser refuses the copy, the dialog unmasks the secret so that you can copy it by hand. Click Done.
| Field | What it takes |
|---|---|
| Name | Required. Up to 255 characters |
| URL | Required. An https URL that is reachable from the internet. Risicare signs each request |
| Events | Required. Choose at least one. See Events |
| Signing secret (optional) | Leave it empty and Risicare makes a secret |
A new webhook is on.
The signing secret shows once
The dashboard shows the secret only in this dialog. Escape and a click outside do not close the dialog. Only Done or the close button close it. The Edit webhook form has no field for the secret. If you lose it, add a new webhook and delete the old one.
Risicare refuses a URL that does not use https, has no host name, points to an internal service or to Risicare itself, or resolves to a private or internal address. The form shows the reason.
Events
The form lists 12 events. Choose the events that this webhook receives.
| Event | Meaning of the name |
|---|---|
trace.completed | A trace completed |
trace.error | A trace has an error |
alert.triggered | An alert rule fired. A test of a rule sends none. See Alerts |
evaluation.completed | An evaluation completed |
This page does not say when Risicare sends trace.completed, trace.error or evaluation.completed, and it does not describe the body of these events. If Risicare cannot send an event now, it refuses the save. The form then reads "These events cannot be sent now" with the names, and "Choose from" with the events that you can choose.
Prompt events
The group Prompts has four events. A prompt event carries names, hashes, numbers, links, and the note and reason written with the change. It never carries prompt text.
| Event | When Risicare sends it |
|---|---|
prompt.label_moved | A label moved to another version. See Labels |
prompt.version_created | A person or a key saved a new version. See Versions |
prompt.promotion_requested | A person asked for a promotion and waits for approval. See Gate and approvals |
prompt.rollback_proposed | A rule found a fall after a move and proposes the previous version. See Rollback |
Events of held features
diagnosis.completed, fix.deployed, fix.graduated and fix.rolled_back belong to features that are held for the beta. See Diagnose and Heal. This page does not describe them.
Send a test event
Send a test event checks that your receiver takes a delivery. It appears on the row of a webhook that is on and subscribes to prompt.label_moved, prompt.version_created or prompt.promotion_requested. A webhook with only prompt.rollback_proposed or the other events has no test.
- Click Send a test event. Risicare queues one delivery of a prompt event. If the webhook has more than one of the three events, the first in the order of the table above is sent.
- The test event has the same keys as a real event. The field
is_testistrue, and the event holds no prompt text. Risicare signs it with the secret of the webhook, as it signs a real event. - The page checks the state every 3 seconds, for up to 60 seconds. It reads "Test event sent to" the webhook, "The receiver took it.", or "The test event to" the webhook "failed" with the reason.
- After 60 seconds without a result, it reads "The test event for" the webhook "is still waiting. Check the list again in a minute."
You can send at most 6 test events in 60 seconds for one webhook. A test event counts in Deliveries and Failures.
Read the list
A row shows the state of the webhook: a play icon when it is on, a pause icon and the badge disabled when it is off. It shows the name, a badge for each event, and the host of the URL. Hover over the host to see the full URL. On the right, a check mark and a number count the deliveries that were sent. A cross and a number count the deliveries that failed. A clock shows when the last delivery happened.
| Counter | What it counts |
|---|---|
| Active | The webhooks that are on, out of all webhooks |
| Deliveries | The deliveries that were sent. Prompt events and other events together |
| Failures | The deliveries that failed for good. Prompt events and other events together |
A delivery of a prompt event is waiting until Risicare sends it. If the receiver refuses it or does not answer, Risicare tries again. After five tries the delivery stays failed. A delivery that waits and a failed try are in neither counter.
The lines under Deliveries and Failures say how much of each number is prompt events. They also count the deliveries that wait and the failed tries. A row with prompt events reads, for example, "Prompt events: 2 sent, 1 waiting, 1 failed for good · 3 failed tries". The page reads these numbers when it loads, so reload it to see new ones. A webhook with more than 50 prompt-event deliveries is counted over its newest 50.
The page does not list single deliveries. The Label history tab of a prompt has the column Notified. Click the count there to read each delivery of a label move and its reason. See Labels.
Edit and delete
- Edit (pencil) opens Edit webhook. You can change the Name, the URL and the Events. The box Send events to this webhook turns the webhook on or off. Click Save webhook. The form sends only the fields that you changed.
- Delete (trash) asks once: "The URL stops receiving events from this project. You cannot restore the webhook from this dashboard." Click Delete webhook to confirm.
Who can manage
Only an owner or an admin of the project adds, changes, deletes and tests webhooks. Other roles see the list and the text "Only an owner or an admin can add, change or delete a webhook." See the permission matrix.
Webhooks and notification channels
A webhook on this page and a webhook channel in Settings → Notifications are two different objects. Adding one does not add the other. A channel receives the firings of the alert rules that choose it. A webhook receives the events that you subscribe it to. A webhook that subscribes to alert.triggered keeps working beside the channels. See Notification Channels.