Webhook Notifications

A webhook channel delivers alerts to an HTTPS endpoint you control. Each time an alert triggers (and, if you enable it, when it resolves), Fleetera sends an HTTP POST with a signed JSON body to the channel's URL.

You create one webhook channel per destination and then attach it to the alerts you want it to deliver. A single channel can serve many alerts.

What a webhook channel needs

Custom header limits

If you supply custom headers, they are bounded to keep requests well-formed:

• At most 20 headers. When you update a channel, the limit applies to the headers the channel has after the update: a header you remove does not count.
• Each header name is at most 128 characters.
• Each header value is at most 4096 characters.

Fleetera sets its own headers on every request (Content-Type, the signature headers, the delivery and event headers — see Verifying Webhook Signatures). If a custom header you provide collides with one of these reserved names, the reserved value takes precedence and your value is dropped.

Header values and query tokens are stored encrypted

A custom header value, such as Authorization: Bearer …, and the query string of the URL, such as ?token=… or ?sig=…, are often credentials for your receiver. Fleetera stores them encrypted and never shows them again after you save:

• Each header shows its name with the value masked as ••••.
• The URL shows without its query string. The channels list shows the host and path, with ?••• when a query string is stored.

To change a stored value, open Edit channel. Under Custom headers, each stored header has Replace and Remove; under the URL, Stored query (hidden) has Replace and Clear. A value you don't touch is kept.

If you change the URL to another host, stored values don't follow it there. Before you can save, re-enter or remove each stored header, and replace or clear the stored query. Changing only the path on the same host keeps them.

Creating a webhook channel

Webhook channels are managed under Notifications → Channels. Choose Create channel, set the type to Webhook, enter the destination URL, and add any custom headers your receiver requires.

Turn on Include resolve notifications if your receiver should also be notified when an alert clears, then choose Create channel.

Channels can also be managed through the platform API. The request below creates a webhook channel:

POST /notification-channels
Content-Type: application/json

{
  "name": "Ops ticketing system",
  "type": "webhook",
  "config": {
    "url": "https://hooks.example.com/fleetera-alerts",
    "headers": {
      "Authorization": "Bearer your-receiver-token"
    },
    "includeResolved": true
  }
}

The response describes the created channel and — for webhook channels — includes the signing secret exactly once, in the secretShownOnce field:

{
  "id": "0b8f2c1e-9d3a-4f57-bb20-2c6f0a1e4d9a",
  "name": "Ops ticketing system",
  "type": "webhook",
  "config": {
    "url": "https://hooks.example.com/fleetera-alerts",
    "urlMasked": "https://hooks.example.com/fleetera-alerts",
    "hasUrlQuery": false,
    "headers": { "Authorization": "••••" },
    "includeResolved": true
  },
  "enabled": true,
  "hasSecret": true,
  "secretShownOnce": "whsec_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "createdAt": "2026-06-10T09:30:00.000Z",
  "updatedAt": "2026-06-10T09:30:00.000Z"
}

The signing secret

Unless the channel uses a provisioned signing secret, the signing secret is generated by Fleetera, not chosen by you, and is unique to each channel. Its only purpose is to let your receiver authenticate incoming requests: Fleetera signs every request body with it, and your endpoint recomputes the signature to confirm the request is genuine. See Verifying Webhook Signatures for the recipe.

Because the secret is part of the channel's identity, treat it as sensitive:

• Store it in a secrets manager or your receiver's environment configuration — never in source control or a shared document.
• Use a distinct receiver per channel where possible, so a single channel's secret only protects one endpoint.

Use a provisioned signing secret

Instead of a generated secret, a channel can sign with a secret that Fleetera staff provision for your organization. Contact Fleetera support to have the secret provisioned under a name, for example ops-hook. It must be at least 32 bytes long. Your receiver verifies signatures with the same secret. Fleetera refuses a value that is an http or https URL or looks like a PagerDuty integration key (32 letters and digits), so a credential meant for another channel cannot become a signing secret.

When you create the channel, under Signing secret, choose Provisioned secret instead of Generate one, and pick the name. The list shows only the secrets that can sign a webhook. If none can, the dialog says so, and you use a generated secret instead. Nothing is shown once after creation: secretShownOnce is null.

• When Fleetera staff rotate the secret, later deliveries are signed with the new value, with no edit to the channel. Have your receiver accept both the old and the new secret until the rotation is done.
• An existing channel with a generated secret can switch: open Edit channel, choose Provisioned secret instead of Current secret, pick the name, and choose Save changes. Saving discards the generated secret for good, and your receiver must verify with the provisioned secret from the next delivery.
• A channel that uses a provisioned secret can switch back: open Edit channel, choose Use a generated secret, and choose Save changes. Fleetera generates a new signing secret and shows it once, the same way it does when you create a channel. Copy it and update your receiver, because deliveries are signed with it from then on.

Through the API, add "secretRef": { "name": "ops-hook" } to config when you create or update the channel. On an update, "secretRef": null switches back to a generated secret, and the response carries it once in secretShownOnce. A name that is not provisioned for your organization is refused with a 422 and the code secret_ref_not_found; a provisioned value shorter than 32 bytes, an http or https URL, or a PagerDuty-shaped key is refused with secret_ref_invalid.

Rotating the secret

The channel dialog does not rotate a generated secret in place. A provisioned signing secret is rotated by Fleetera staff instead. To roll a generated secret:

1. Create a new webhook channel pointing at the same URL and copy its secretShownOnce.
2. Update your receiver to accept signatures from either secret during a short overlap window.
3. Move your alerts over to the new channel.
4. Once no traffic is arriving on the old channel, delete it and remove the old secret from your receiver.

Updating and removing a channel

You can rename a channel, change its URL or headers, and enable or disable it after creation. Header values and the URL's query string stay masked; see Header values and query tokens are stored encrypted. A channel's type cannot be changed — to switch a destination to a different channel type, create a new channel. Updating a webhook channel never returns the signing secret again; the existing secret continues to apply.

Through the API, send the changes with PATCH /notification-channels/{channelId}. Stored header values and the stored query merge with what you send:

• In headers, a header with a value sets it, a header set to null is removed, and a header set to "••••" keeps its stored value. A header you don't name is kept.
• A url without a query string keeps the stored query, and a url with one replaces it. To remove the stored query, send "clearUrlQuery": true.
• If the url moves to another host, give every stored header a new value or null, and replace or clear the stored query. Otherwise the update is refused with a 400 and the code webhook_secrets_reentry_required, which names the headers and the query still to re-enter.

For older channels where no resolve preference was set, resolve notifications remain enabled. To stop them, open Edit channel, turn off Include resolve notifications, and choose Save changes. This also stops retries of resolve notifications that have not yet been delivered.

Verifying a channel works

Before you rely on a channel, send a test notification to confirm your endpoint receives and accepts a signed request. The test-send walkthrough covers this end to end, including how to read the delivery result.

Custom body

Expand Custom body template (optional) in the channel dialog to adapt the JSON body for your receiver. Use Preview rendered body to check a sample without sending it. See Webhook body templates for starter templates, syntax, and variables.