curl --request POST \
--url https://app.blockgence.com/v1/guard/webhooks \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"url": "<string>",
"scope": "mine",
"watch_id": 123,
"min_severity": "high",
"description": ""
}
'import requests
url = "https://app.blockgence.com/v1/guard/webhooks"
payload = {
"url": "<string>",
"scope": "mine",
"watch_id": 123,
"min_severity": "high",
"description": ""
}
headers = {
"X-API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
url: '<string>',
scope: 'mine',
watch_id: 123,
min_severity: 'high',
description: ''
})
};
fetch('https://app.blockgence.com/v1/guard/webhooks', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://app.blockgence.com/v1/guard/webhooks",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'url' => '<string>',
'scope' => 'mine',
'watch_id' => 123,
'min_severity' => 'high',
'description' => ''
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-API-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://app.blockgence.com/v1/guard/webhooks"
payload := strings.NewReader("{\n \"url\": \"<string>\",\n \"scope\": \"mine\",\n \"watch_id\": 123,\n \"min_severity\": \"high\",\n \"description\": \"\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-API-Key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://app.blockgence.com/v1/guard/webhooks")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"url\": \"<string>\",\n \"scope\": \"mine\",\n \"watch_id\": 123,\n \"min_severity\": \"high\",\n \"description\": \"\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://app.blockgence.com/v1/guard/webhooks")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"url\": \"<string>\",\n \"scope\": \"mine\",\n \"watch_id\": 123,\n \"min_severity\": \"high\",\n \"description\": \"\"\n}"
response = http.request(request)
puts response.read_body{
"detail": "<string>",
"error": "<string>"
}{
"detail": "<string>",
"error": "<string>"
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>",
"input": "<unknown>",
"ctx": {}
}
]
}{
"detail": "<string>",
"error": "<string>"
}Create a webhook
Creates a signed webhook that receives Guard alerts by POST with a JSON body.
Body: {"url": "https://…", "scope": "mine", "watch_id": null, "min_severity": "high", "description": "…"}.
scope: which alerts it receives.mine(the default): those of the watches owned by the person who creates it.org: those of the organization’s shared watches, not each person’s private ones. An administrator of the organization creates it, and it stops receiving if that person is no longer active in the organization.watch: those of one watch and its derived watches, given inwatch_id. Created by someone who can edit that watch.min_severity: the minimum severity that is notified (low,medium,highorcritical);highby default.url:https, on port 443, without user or password and with a host that resolves to public IP addresses. It is validated when the webhook is created and on every delivery.
Up to 10 webhooks per organization.
Returns the webhook with the full secret only once (secret_shown_once: true). After that, the secret is
shown masked.
Messages. One POST is sent per alert and per event. type is guard.alert.created (a new alert),
guard.alert.retracted (a chain reorganization removed the transaction), guard.alert.revived (the
transaction was included again), guard.alert.updated (a person changed the alert) or guard.test. The body
includes type, timestamp, api_version and data, with alert (the same facts as
GET /v1/guard/alerts/{aid} and status at the time of delivery), watch and webhook. guard.alert.updated
adds data.change, with who made the change and which fields changed; for a comment, it only states that one was
added. The body does not include email addresses or names of people.
Signature (Standard Webhooks). Each message carries three headers:
webhook-id: the message id. It is the same on every retry; use it to avoid processing a message twice.webhook-timestamp: the time of delivery, in unix seconds.webhook-signature:v1,<base64>, the HMAC-SHA256 of"{webhook-id}.{webhook-timestamp}.{body}". The key is the base64 bytes that followwhsec_in the secret.
To verify a message: compute the signature over the raw body, before parsing the JSON; compare it in constant
time with each v1,… in the header; reject a webhook-timestamp more than 5 minutes off, and discard a
webhook-id already processed. The Standard Webhooks libraries perform this verification with the same secret.
Delivery. Any 2xx response counts as delivered. On any other response or no response, delivery is retried
after 30 s, 2 min, 10 min, 30 min, 1 h, 2 h, 4 h and 8 h (about 15 hours in total), with the same webhook-id;
after that, the delivery becomes failed. A notification that could not be sent within 3 days expires
(expired). Order is preserved within the same alert, but not across different alerts: use data.alert.id and
timestamp. A 410 Gone response or 30 consecutive failures disable the webhook. Redirects are not followed.
Errors:
400: invalid or non-public URL, invalid scope or severity,scope: "watch"withoutwatch_id, orwatch_idwith another scope.403: theorgscope without being an administrator of the organization, a watch the requester cannot edit, the webhook limit reached, or an API key not assigned to a person.404: a watch the requester cannot view.422: the body contains an unknown field.
Cost: free.
curl --request POST \
--url https://app.blockgence.com/v1/guard/webhooks \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"url": "<string>",
"scope": "mine",
"watch_id": 123,
"min_severity": "high",
"description": ""
}
'import requests
url = "https://app.blockgence.com/v1/guard/webhooks"
payload = {
"url": "<string>",
"scope": "mine",
"watch_id": 123,
"min_severity": "high",
"description": ""
}
headers = {
"X-API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
url: '<string>',
scope: 'mine',
watch_id: 123,
min_severity: 'high',
description: ''
})
};
fetch('https://app.blockgence.com/v1/guard/webhooks', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://app.blockgence.com/v1/guard/webhooks",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'url' => '<string>',
'scope' => 'mine',
'watch_id' => 123,
'min_severity' => 'high',
'description' => ''
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-API-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://app.blockgence.com/v1/guard/webhooks"
payload := strings.NewReader("{\n \"url\": \"<string>\",\n \"scope\": \"mine\",\n \"watch_id\": 123,\n \"min_severity\": \"high\",\n \"description\": \"\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-API-Key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://app.blockgence.com/v1/guard/webhooks")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"url\": \"<string>\",\n \"scope\": \"mine\",\n \"watch_id\": 123,\n \"min_severity\": \"high\",\n \"description\": \"\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://app.blockgence.com/v1/guard/webhooks")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"url\": \"<string>\",\n \"scope\": \"mine\",\n \"watch_id\": 123,\n \"min_severity\": \"high\",\n \"description\": \"\"\n}"
response = http.request(request)
puts response.read_body{
"detail": "<string>",
"error": "<string>"
}{
"detail": "<string>",
"error": "<string>"
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>",
"input": "<unknown>",
"ctx": {}
}
]
}{
"detail": "<string>",
"error": "<string>"
}Authorizations
Headers
Body
Response
Successful response.