Skip to main content

Webhook alert method

Reading time: 0 minute(s) (0 words)

The webhook alert method sends alerts through an HTTP callback handler that is triggered by an event. You can create webhooks and configure them to handle different incident notifications using either custom or predefined notification templates.

Adding the Webhook alert method​

You can add the Webhook alert method directly in the Nobl9 Web application.

Alternatively, utilize the SLOs-as-code approach by:

Nobl9 Web​

To set up the alert method on the Nobl9 Web, follow these steps:

  1. Navigate to Integrations > Alert methods.
  2. Click .
  3. Select Webhook.

  1. Enter the URL (mandatory).
    Your webhook endpoint HTTP POST requests will be sent to.
    The URL must start with https://.

  2. Select a Project (mandatory).
    Projects provide the structure for organizing Nobl9 resources and managing access permissions.
    If a project is not specified, Nobl9 assigns the default project value automatically.
  3. Enter a Display Name (optional).
    Spaces are allowed.
  4. Enter a Name (mandatory).
    It can only contain lowercase, alphanumeric characters, and dashes (for example, my-alert-method-1). Nobl9 auto-populates this field based on the display name you enter, transforming it into the supported format. You can edit the result.
  5. Enter a Description (optional).
    Provide extra details, such as the purpose and responsible personnel.
    Up to 1050 characters.

  6. In the Custom headers block, you can add customized headers to be sent along with Webhook notifications (optional). To add a custom header:

    1. Click blue plus icon.
    2. Enter Key and Value
      • For Key, use only letters, numbers, hyphens (-), and underscores (_). It must start with a letter or number.

  7. Configure Notification details to define the response payload details (mandatory):

    • Nobl9: select at least one field from the list of predefined details.

    • Custom: create a custom payload or click Insert to use templated field values. Only JSON is accepted:

      • Enclose each field name in double quotes ("<field_name>")
      • Indicate variables with $, use lowercase letters, and separate words with _
      • When you expect to receive an array, add square brackets ([]) after the value
      For example
          {
          "policy": $alert_policy_conditions[],
          "message": "Your SLO $slo_name needs attention!"
          }
  8. Click Add alert method.

YAML configuration​

YAML for the webhook integration supports custom notification message templates. The template can be specified in two ways:

  • Only variables are specified, and the notification message is generated automatically
  • A full message template is specified, with variables in the form $<variable_name>
General YAML sample for Webhook alert method
apiVersion: n9/v1alpha
kind: AlertMethod
metadata:
  name: string # Mandatory
  displayName: string # Optional
  project: default # Mandatory
  # Optional
  # The key value: only alphanumeric characters, `-`, `_`, or `.` are allowed.
  # The key value must start and end with an alphanumeric character.
  # An optional DNS subdomain prefix followed by `/` is allowed.
  annotations:
    key: value
spec:
  description: string # Optional
  webhook:
    url: string # Mandatory, must start with https://
    # Either `templateFields` or `template` must be specified, but not both.
    templateFields: # array of strings
      - string1
      - string2
    # Replace the `templateFields` with `template` if a full template is used
    # template: string

Important notes:

  • In your Webhook YAML definition, define either of the following objects:

    • spec.webhook.template

    • spec.webhook.templateFields

  • The difference between alert_policy_conditions[] and alert_policy_conditions_text is that alert_policy_conditions[] creates a valid JSON array of conditions as strings, whereas alert_policy_conditions_text creates a single string field. For example:

    {
      "text": "Remaining error budget is 10%, Error budget would be exhausted in 15 minutes and this condition lasts for 1 hour",
      "array": [
        "Remaining error budget is 10%",
        "Error budget would be exhausted in 15 minutes and this condition lasts for 1 hour"
      ]
    }

  • slo_labels_text, service_labels_text, and alert_policy_labels_text are comma-separated key:value pairs. For example:

    • slo:ratio, slo:calendar

    • project:myproject

    • alert:low, alert:high

Testing the webhook alert policy in the UI​

You can test alert methods for all notification services supported by the Nobl9 platform through the UI.

To verify the correctness of your alert method configuration:

  1. Navigate to Integrations > Alert methods.
  2. Click the required alert method.
    Its Details page opens.
  3. Click Test under the alert method name:

    • When the configuration is correct, Nobl9 displays Test completed successfully! under the button.
    • Otherwise, the Test failed message appears. It contains the details of incorrect settings.

Verifying webhook signatures​

Nobl9 signs all webhook notifications with HTTP Message Signatures. Use the signature to verify that a webhook notification came from Nobl9 and that the signed request fields and body were not changed in transit.

Signed webhook requests include the following HTTP headers:

HeaderDescription
Content-DigestSHA-256 digest of the raw request body.
Signature-InputRFC 9421 sig1 metadata: covered components, creation time, key ID, and signing algorithm.
SignatureEd25519 signature for the signature base described by Signature-Input.

The Signature-Input header uses the sig1 label. It includes keyid and alg="ed25519" parameters, and covers the following request components:

@method
@authority
@path
content-digest
content-type

The query string is not covered by the signature. If your webhook URL includes query parameters, do not use them as signed data.

To verify a webhook notification, implement the following checks in your endpoint:

  1. Read the raw request body before parsing it.

  2. Calculate the SHA-256 digest of the raw body and compare it with the Content-Digest header.

  3. Fetch the active Nobl9 public key for your environment:

    InstanceEndpoint
    EU (app)GET https://app.nobl9.com/api/notifications/v1/webhook-http-signature/public-key
    US (us1)GET https://us1.nobl9.com/api/notifications/v1/webhook-http-signature/public-key

  4. Check that the response keyId matches the keyid value in the Signature-Input header.

  5. Rebuild the RFC 9421 signature base from the covered components listed in Signature-Input.

  6. Verify the Signature header with the public key and Ed25519 algorithm.

  7. Process the notification only when both the body digest and the signature are valid.

For example, if your endpoint receives the raw body {} with this request target and headers:

POST https://example.com/nobl9/webhook?source=nobl9
Content-Type: application/json
Content-Digest: sha-256=:RBNvo1WzZ4oRRq0W9+hknpT7T8If536DEMBg9hyq/4o=:
Signature-Input: sig1=("@method" "@authority" "@path" "content-digest" "content-type");created=1778498701;keyid="nobl9-webhook-prod-ed25519-v1";alg="ed25519"

then build the signature base as this exact newline-separated string:

"@method": POST
"@authority": example.com
"@path": /nobl9/webhook
"content-digest": sha-256=:RBNvo1WzZ4oRRq0W9+hknpT7T8If536DEMBg9hyq/4o=:
"content-type": application/json
"@signature-params": ("@method" "@authority" "@path" "content-digest" "content-type");created=1778498701;keyid="nobl9-webhook-prod-ed25519-v1";alg="ed25519"

Verify the Signature header against the UTF-8 bytes of this string. The query string, ?source=nobl9 in this example, is not included in @path.

The public key endpoint returns a JSON response similar to this:

{
  "keyId": "nobl9-webhook-prod-ed25519-v1",
  "algorithm": "ed25519",
  "publicKeyPem": "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----\n"
}

Your verifier must build the signature base from the request as received by your endpoint. If you use a proxy, make sure it preserves the original host, port, path, Content-Digest, and Content-Type values used for verification.

Check out these related guides and references:
Webhook alert methodTerraform provider
Last updated on
On this page