MetriBeacon
Menu

POST Create a named destination or register a browser push subscription

/api/v1/notifications/destinations

CSRF protected; supports Idempotency-Key. The current verified account email is confirmed automatically; other email recipients require a one-time verification. Telegram requires a private /start proof. The default limit is 20 destinations per account and is centrally configurable. A webhook signing_secret is returned only in the first response.

On this page

Access and permissions

CSRF protected; supports Idempotency-Key. The current verified account email is confirmed automatically; other email recipients require a one-time verification. Telegram requires a private /start proof. The default limit is 20 destinations per account and is centrally configurable. A webhook signing_secret is returned only in the first response.

Browser session: __Host-mb_session cookie.

Machine management credentials in Authorization: Bearer. Check the permissions (scopes) required by the operation.

When using a browser session for a mutation, send the current CSRF token in X-CSRF-Token with the same-site cookie. OAuth consent uses its documented form field.

Parameters and headers

No path, query or additional request-header parameters.

Request body

FieldType and limitsRequiredMeaning
$NotificationDestinationCreateYes—
$.channelstring; {"enum":["email","telegram","discord","slack","ntfy","webpush","webhook","pagerduty","opsgenie","jsm","google_chat","teams","slack_app","sms","voice"]}Yes—
$.configNotificationConnectionNoCredentials are encrypted and never returned by read endpoints. HTTP URLs require public HTTPS on port 443. Internal and host destinations, redirects and mixed public/private DNS answers are denied.
$.config.passwordstring; {"maxLength":4096}No—
$.config.serverstring; {"format":"uri","maxLength":2048}Nontfy server; defaults to https://ntfy.sh
$.config.subscriptionobjectNo—
$.config.subscription.endpointstring; {"format":"uri"}Yes—
$.config.subscription.keysobjectYes—
$.config.subscription.keys.authstringYes—
$.config.subscription.keys.p256dhstringYes—
$.config.tokenstring; {"maxLength":4096}NoOptional bearer token for ntfy or HTTP webhook
$.config.topicstring; {"maxLength":64}No—
$.config.urlstring; {"format":"uri","maxLength":2048}No—
$.config.usernamestring; {"maxLength":256}Nontfy basic authentication; alternative to bearer
$.config.regionstringNo—
$.config.teamstringNo—
$.config.channelstringNo—
$.config.account_sidstringNo—
$.config.fromstringNo—
$.config.tostringNo—
$.config.backchannel_secretstringNo—
$.config.installation_idstringNo—
$.config.daily_budgetinteger; {"minimum":1,"maximum":1000}No—
$.config.provider_modestring; {"default":"own","enum":["own","managed"]}No—
$.emailstring; {"format":"email"}NoEmail only; separate recipient verification
$.enabledboolean; {"default":false}No—
$.namestring; {"maxLength":128}Yes—

Responses

HeaderType and limitsMeaning
Cache-Controlstring; {"pattern":"(?:^|,\\s*)no-store(?:,|$)"}Private API responses prohibit storage. Public OAuth metadata is cached for 300 seconds; live streams additionally prohibit transformation.
Content-Languagestring; {"enum":["en","de"]}Language of human-readable response text, resolved from Accept-Language or the documented browser preference. Technical codes and identifiers remain stable.
Referrer-PolicyJSON; {"enum":["strict-origin-when-cross-origin","no-referrer"]}The default referrer policy is strict-origin-when-cross-origin. Provider-login responses use no-referrer to protect login parameters.
VarystringResponses vary by Accept-Language; browser-rendered responses can also vary by the preference cookie.
X-Content-Type-OptionsJSON; {"const":"nosniff"}The browser must use the declared content type.
X-Frame-OptionsJSON; {"const":"DENY"}The response must not be embedded in a frame.
X-Request-IDstringServer-generated request identifier. Include this when reporting an error; inbound values are not trusted.

application/json

FieldType and limitsRequiredMeaning
$object | objectYes—
$ (anyOf 1)objectNo—
$ (anyOf 1).idJSONYes—
$ (anyOf 2)objectNo—
$ (anyOf 2).enabledbooleanYes—
$ (anyOf 2).idstringYes—
$ (anyOf 2).signing_secretstringYes—
$ (anyOf 2).verifiedbooleanYes—
Stable error codes
unauthorized
HeaderType and limitsMeaning
Cache-Controlstring; {"pattern":"(?:^|,\\s*)no-store(?:,|$)"}Private API responses prohibit storage. Public OAuth metadata is cached for 300 seconds; live streams additionally prohibit transformation.
Content-Languagestring; {"enum":["en","de"]}Language of human-readable response text, resolved from Accept-Language or the documented browser preference. Technical codes and identifiers remain stable.
Referrer-PolicyJSON; {"enum":["strict-origin-when-cross-origin","no-referrer"]}The default referrer policy is strict-origin-when-cross-origin. Provider-login responses use no-referrer to protect login parameters.
VarystringResponses vary by Accept-Language; browser-rendered responses can also vary by the preference cookie.
X-Content-Type-OptionsJSON; {"const":"nosniff"}The browser must use the declared content type.
X-Frame-OptionsJSON; {"const":"DENY"}The response must not be embedded in a frame.
X-Request-IDstringServer-generated request identifier. Include this when reporting an error; inbound values are not trusted.

application/problem+json

FieldType and limitsRequiredMeaning
$ProblemYes—
$.codestringYesStable machine-readable error code
$.detailstringYesShort localized explanation without internal error details
$.instancestringYesUnique relative identifier /api/v1/requests/{request_id}; not a retrievable resource
$.messagestringYesTemporarily identical to detail for existing clients
$.message_keystringYesStable translation key for changing the displayed language without another request
$.message_paramsobject; {"additionalProperties":true}YesNamed, safely rendered message parameters; never arbitrary HTML
$.request_idstring; {"pattern":"^[0-9a-f]{32}$"}YesServer-generated diagnostic identifier. It contains no login token or credential.
$.statusinteger; {"maximum":599,"minimum":400}Yes—
$.titlestringYesLocalized HTTP status title
$.typestring; {"const":"about:blank"}Yes—
Stable error codes
forbidden
HeaderType and limitsMeaning
Cache-Controlstring; {"pattern":"(?:^|,\\s*)no-store(?:,|$)"}Private API responses prohibit storage. Public OAuth metadata is cached for 300 seconds; live streams additionally prohibit transformation.
Content-Languagestring; {"enum":["en","de"]}Language of human-readable response text, resolved from Accept-Language or the documented browser preference. Technical codes and identifiers remain stable.
Referrer-PolicyJSON; {"enum":["strict-origin-when-cross-origin","no-referrer"]}The default referrer policy is strict-origin-when-cross-origin. Provider-login responses use no-referrer to protect login parameters.
VarystringResponses vary by Accept-Language; browser-rendered responses can also vary by the preference cookie.
X-Content-Type-OptionsJSON; {"const":"nosniff"}The browser must use the declared content type.
X-Frame-OptionsJSON; {"const":"DENY"}The response must not be embedded in a frame.
X-Request-IDstringServer-generated request identifier. Include this when reporting an error; inbound values are not trusted.

application/problem+json

FieldType and limitsRequiredMeaning
$ProblemYes—
$.codestringYesStable machine-readable error code
$.detailstringYesShort localized explanation without internal error details
$.instancestringYesUnique relative identifier /api/v1/requests/{request_id}; not a retrievable resource
$.messagestringYesTemporarily identical to detail for existing clients
$.message_keystringYesStable translation key for changing the displayed language without another request
$.message_paramsobject; {"additionalProperties":true}YesNamed, safely rendered message parameters; never arbitrary HTML
$.request_idstring; {"pattern":"^[0-9a-f]{32}$"}YesServer-generated diagnostic identifier. It contains no login token or credential.
$.statusinteger; {"maximum":599,"minimum":400}Yes—
$.titlestringYesLocalized HTTP status title
$.typestring; {"const":"about:blank"}Yes—
Stable error codes
destination_unavailable
idempotency_conflict
subscription_exists
HeaderType and limitsMeaning
Cache-Controlstring; {"pattern":"(?:^|,\\s*)no-store(?:,|$)"}Private API responses prohibit storage. Public OAuth metadata is cached for 300 seconds; live streams additionally prohibit transformation.
Content-Languagestring; {"enum":["en","de"]}Language of human-readable response text, resolved from Accept-Language or the documented browser preference. Technical codes and identifiers remain stable.
Referrer-PolicyJSON; {"enum":["strict-origin-when-cross-origin","no-referrer"]}The default referrer policy is strict-origin-when-cross-origin. Provider-login responses use no-referrer to protect login parameters.
VarystringResponses vary by Accept-Language; browser-rendered responses can also vary by the preference cookie.
X-Content-Type-OptionsJSON; {"const":"nosniff"}The browser must use the declared content type.
X-Frame-OptionsJSON; {"const":"DENY"}The response must not be embedded in a frame.
X-Request-IDstringServer-generated request identifier. Include this when reporting an error; inbound values are not trusted.

application/problem+json

FieldType and limitsRequiredMeaning
$ProblemYes—
$.codestringYesStable machine-readable error code
$.detailstringYesShort localized explanation without internal error details
$.instancestringYesUnique relative identifier /api/v1/requests/{request_id}; not a retrievable resource
$.messagestringYesTemporarily identical to detail for existing clients
$.message_keystringYesStable translation key for changing the displayed language without another request
$.message_paramsobject; {"additionalProperties":true}YesNamed, safely rendered message parameters; never arbitrary HTML
$.request_idstring; {"pattern":"^[0-9a-f]{32}$"}YesServer-generated diagnostic identifier. It contains no login token or credential.
$.statusinteger; {"maximum":599,"minimum":400}Yes—
$.titlestringYesLocalized HTTP status title
$.typestring; {"const":"about:blank"}Yes—
Stable error codes
invalid_destination
invalid_email
invalid_secret
HeaderType and limitsMeaning
Cache-Controlstring; {"pattern":"(?:^|,\\s*)no-store(?:,|$)"}Private API responses prohibit storage. Public OAuth metadata is cached for 300 seconds; live streams additionally prohibit transformation.
Content-Languagestring; {"enum":["en","de"]}Language of human-readable response text, resolved from Accept-Language or the documented browser preference. Technical codes and identifiers remain stable.
Referrer-PolicyJSON; {"enum":["strict-origin-when-cross-origin","no-referrer"]}The default referrer policy is strict-origin-when-cross-origin. Provider-login responses use no-referrer to protect login parameters.
VarystringResponses vary by Accept-Language; browser-rendered responses can also vary by the preference cookie.
X-Content-Type-OptionsJSON; {"const":"nosniff"}The browser must use the declared content type.
X-Frame-OptionsJSON; {"const":"DENY"}The response must not be embedded in a frame.
X-Request-IDstringServer-generated request identifier. Include this when reporting an error; inbound values are not trusted.

application/problem+json

FieldType and limitsRequiredMeaning
$ProblemYes—
$.codestringYesStable machine-readable error code
$.detailstringYesShort localized explanation without internal error details
$.instancestringYesUnique relative identifier /api/v1/requests/{request_id}; not a retrievable resource
$.messagestringYesTemporarily identical to detail for existing clients
$.message_keystringYesStable translation key for changing the displayed language without another request
$.message_paramsobject; {"additionalProperties":true}YesNamed, safely rendered message parameters; never arbitrary HTML
$.request_idstring; {"pattern":"^[0-9a-f]{32}$"}YesServer-generated diagnostic identifier. It contains no login token or credential.
$.statusinteger; {"maximum":599,"minimum":400}Yes—
$.titlestringYesLocalized HTTP status title
$.typestring; {"const":"about:blank"}Yes—
Stable error codes
destination_limit
verification_limit
HeaderType and limitsMeaning
Cache-Controlstring; {"pattern":"(?:^|,\\s*)no-store(?:,|$)"}Private API responses prohibit storage. Public OAuth metadata is cached for 300 seconds; live streams additionally prohibit transformation.
Content-Languagestring; {"enum":["en","de"]}Language of human-readable response text, resolved from Accept-Language or the documented browser preference. Technical codes and identifiers remain stable.
Referrer-PolicyJSON; {"enum":["strict-origin-when-cross-origin","no-referrer"]}The default referrer policy is strict-origin-when-cross-origin. Provider-login responses use no-referrer to protect login parameters.
VarystringResponses vary by Accept-Language; browser-rendered responses can also vary by the preference cookie.
X-Content-Type-OptionsJSON; {"const":"nosniff"}The browser must use the declared content type.
X-Frame-OptionsJSON; {"const":"DENY"}The response must not be embedded in a frame.
X-Request-IDstringServer-generated request identifier. Include this when reporting an error; inbound values are not trusted.

application/problem+json

FieldType and limitsRequiredMeaning
$ProblemYes—
$.codestringYesStable machine-readable error code
$.detailstringYesShort localized explanation without internal error details
$.instancestringYesUnique relative identifier /api/v1/requests/{request_id}; not a retrievable resource
$.messagestringYesTemporarily identical to detail for existing clients
$.message_keystringYesStable translation key for changing the displayed language without another request
$.message_paramsobject; {"additionalProperties":true}YesNamed, safely rendered message parameters; never arbitrary HTML
$.request_idstring; {"pattern":"^[0-9a-f]{32}$"}YesServer-generated diagnostic identifier. It contains no login token or credential.
$.statusinteger; {"maximum":599,"minimum":400}Yes—
$.titlestringYesLocalized HTTP status title
$.typestring; {"const":"about:blank"}Yes—
Stable error codes
notification_unavailable
unavailable
HeaderType and limitsMeaning
Cache-Controlstring; {"pattern":"(?:^|,\\s*)no-store(?:,|$)"}Private API responses prohibit storage. Public OAuth metadata is cached for 300 seconds; live streams additionally prohibit transformation.
Content-Languagestring; {"enum":["en","de"]}Language of human-readable response text, resolved from Accept-Language or the documented browser preference. Technical codes and identifiers remain stable.
Referrer-PolicyJSON; {"enum":["strict-origin-when-cross-origin","no-referrer"]}The default referrer policy is strict-origin-when-cross-origin. Provider-login responses use no-referrer to protect login parameters.
VarystringResponses vary by Accept-Language; browser-rendered responses can also vary by the preference cookie.
X-Content-Type-OptionsJSON; {"const":"nosniff"}The browser must use the declared content type.
X-Frame-OptionsJSON; {"const":"DENY"}The response must not be embedded in a frame.
X-Request-IDstringServer-generated request identifier. Include this when reporting an error; inbound values are not trusted.

application/problem+json

FieldType and limitsRequiredMeaning
$ProblemYes—
$.codestringYesStable machine-readable error code
$.detailstringYesShort localized explanation without internal error details
$.instancestringYesUnique relative identifier /api/v1/requests/{request_id}; not a retrievable resource
$.messagestringYesTemporarily identical to detail for existing clients
$.message_keystringYesStable translation key for changing the displayed language without another request
$.message_paramsobject; {"additionalProperties":true}YesNamed, safely rendered message parameters; never arbitrary HTML
$.request_idstring; {"pattern":"^[0-9a-f]{32}$"}YesServer-generated diagnostic identifier. It contains no login token or credential.
$.statusinteger; {"maximum":599,"minimum":400}Yes—
$.titlestringYesLocalized HTTP status title
$.typestring; {"const":"about:blank"}Yes—

Retries and asynchronous work

Save an Idempotency-Key before sending. Retry it only for the same target and unchanged request. A changed payload returns 409. Use this header only where the endpoint documents it.

Request examples

Replace demo IDs, timestamps and placeholders with your own values. For a retry, keep the same IDs, time and content. These examples do not run requests on this page.

Keep login links, codes, cookies and keys private. Do not print them in logs or share them in support requests.

shell
curl --silent --show-error --output /dev/null --write-out "%{http_code}\n" \
  --request POST \
  --header @"$HOME/.config/metribeacon/headers.txt" \
  --header "Content-Type: application/json" \
  --data-binary '{"channel":"webhook","name":"Demo receiver","enabled":true,"config":{"url":"https://receiver.example/notifications"}}' \
  "https://metribeacon.com/api/v1/notifications/destinations"
python
import json
from pathlib import Path
from urllib.request import Request, HTTPRedirectHandler, build_opener
from urllib.error import HTTPError

headers = json.loads((Path.home() / ".config/metribeacon/headers.json").read_text())
headers["Content-Type"] = "application/json"
request = Request("https://metribeacon.com/api/v1/notifications/destinations", data="{\"channel\":\"webhook\",\"name\":\"Demo receiver\",\"enabled\":true,\"config\":{\"url\":\"https://receiver.example/notifications\"}}".encode("utf-8"), headers=headers, method="POST")
class NoRedirect(HTTPRedirectHandler):
    def redirect_request(self, request, fp, code, message, headers, target):
        return None

opener = build_opener(NoRedirect())
try:
    with opener.open(request, timeout=10) as response:
        print(response.status)
except HTTPError as error:
    print(error.code)
    error.close()
javascript
import { readFile } from "node:fs/promises";
import { homedir } from "node:os";
import { join } from "node:path";

const headers = JSON.parse(await readFile(join(homedir(), ".config/metribeacon/headers.json"), "utf8"));
headers["Content-Type"] = "application/json";
const response = await fetch("https://metribeacon.com/api/v1/notifications/destinations", {
  method: "POST", headers, redirect: "manual",
  signal: AbortSignal.timeout(10000), body: "{\"channel\":\"webhook\",\"name\":\"Demo receiver\",\"enabled\":true,\"config\":{\"url\":\"https://receiver.example/notifications\"}}",
});
console.log(response.status);
await response.body?.cancel();
go
package main

import (
  "fmt"
  "net/http"
  "time"
  "encoding/json"
  "os"
  "path/filepath"
  "strings"
)

func main() {
  home, err := os.UserHomeDir(); if err != nil { panic("request failed; credentials and response omitted") }
  raw, err := os.ReadFile(filepath.Join(home, ".config/metribeacon/headers.json")); if err != nil { panic("request failed; credentials and response omitted") }
  var headers map[string]string
  if json.Unmarshal(raw, &headers) != nil { panic("invalid local headers") }
  request, err := http.NewRequest("POST", "https://metribeacon.com/api/v1/notifications/destinations", strings.NewReader("{\"channel\":\"webhook\",\"name\":\"Demo receiver\",\"enabled\":true,\"config\":{\"url\":\"https://receiver.example/notifications\"}}"))
  if err != nil { panic("request failed; credentials and response omitted") }
  for name, value := range headers { request.Header.Set(name, value) }
  request.Header.Set("Content-Type", "application/json")
  client := &http.Client{Timeout: 10*time.Second, CheckRedirect: func(*http.Request, []*http.Request) error { return http.ErrUseLastResponse }}
  response, err := client.Do(request)
  if err != nil { panic("request failed; credentials and response omitted") }
  defer response.Body.Close()
  fmt.Println(response.StatusCode)
}