Webhooks

A webhook is a URL that an external system calls to make something happen in one of your workspaces. It needs no StratoNext account on the calling side: the caller proves itself with the webhook’s secret, and everything the call does is recorded in the audit trail as that webhook.

A webhook does one of two things:

• Create a task: a task is created and dispatched to an agent. The caller says, per call, which project or deployment it is about, which agent should take it, and what the task’s name, description and instructions are. The request payload is handed to the agent as data. Use it to turn an alert, a ticket or a CI event into an agent doing real work.
• Discover a deployment: infrastructure discovery runs again on the deployment the caller names, so its resource graph and signals reflect what is deployed now. Use it from a deploy pipeline, after the stack has changed.

One webhook serves many callers. What you set on the webhook itself is only a default, used when a call does not say otherwise.

Create a webhook

1. Open the workspace, go to Settings and find Webhooks.
2. Give it a name and pick what it does.
3. For a task webhook, optionally set a default agent, task description and agent instructions. A call that names no agent, or sends no description, falls back to these; a call that has neither is refused, so set the defaults for callers that cannot send them.
4. Optionally pick a default project or deployment, for calls that name neither.
5. Save. The dialog shows the webhook’s URL and its secret.

Caution

The secret is shown only once. Store it in your secret manager before closing the dialog, which asks you to confirm you have. If it leaks, rotate it from the webhook: the old secret stops working immediately and a new one is shown, again only once.

Call it

Send an HTTP POST to the webhook’s URL:

https://api.prod.stratonext.com/v1/webhooks/<webhook-id>

Authentication

Send the secret in one of three ways. The first that is present wins.

Where	How
Authorization header	Authorization: Bearer <secret>
X-StratoNext-Webhook-Secret header	the secret, bare
secret query parameter	?secret=<secret>, for senders that cannot set headers

Prefer a header. A secret in the URL ends up in proxy and access logs on the sending side, so keep that form for senders that give you no other option, and rotate the secret if those logs are shared.

Target and agent

Say what the call is about with query parameters:

Parameter	Meaning
deploymentId	The deployment to discover, or to attach the task to.
projectId	For a task webhook, the project to create the task in.
agentId	For a task webhook, the agent to assign this call’s task to.

Each is optional when the webhook has a default for it; a value in the call replaces the default. Everything must belong to the webhook’s workspace; anything else is a 404. A task call with no project or deployment, or no agent, from either the call or the defaults is a 400.

Body

For a task webhook the body can set the task’s text and carry the data for the agent:

{
  "task": {
    "name": "Checkout 5xx spike",
    "description": "Find out why checkout is returning errors and report the cause.",
    "instructions": "Start from the error logs of the last 30 minutes."
  },
  "payload": { "service": "checkout", "errorRate": 0.12 }
}

Every field is optional. A missing name, description or instructions falls back to the webhook’s default; a call with no description from either side is a 400. The payload can be any JSON and is appended, as data, to the task’s instructions.

A body that is not shaped like this is treated entirely as the payload, so a monitoring tool can post its own notification format unchanged and the webhook’s defaults supply the task text. JSON is the usual choice, but any text works. The body may be at most 32 KB. A discovery webhook ignores the body.

Duplicates

Senders often retry. Send an Idempotency-Key header (1 to 128 characters of letters, digits, ., _, : and -) that is the same across retries of one event. A retry with a key that was already accepted returns the original delivery with 200 and Idempotent-Replayed: true instead of acting twice. The same key with a different body is rejected with 422.

Without a key, two calls with an identical body are treated as the same delivery.

Example

curl -X POST "https://api.prod.stratonext.com/v1/webhooks/<webhook-id>?deploymentId=<deployment-id>&agentId=<agent-id>" \
  -H "Authorization: Bearer <secret>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: alert-4711" \
  -d '{
    "task": { "name": "HighErrorRate on checkout", "description": "Investigate the alert and report the likely cause." },
    "payload": { "alert": "HighErrorRate", "service": "checkout", "state": "firing" }
  }'

Responses

Status	Meaning
202	Accepted. The body names the delivery and, for a task webhook, the task that was created.
200	Replayed: a duplicate of an earlier delivery, which is returned instead.
400	Malformed request, an invalid Idempotency-Key, or no target, agent or description from either the call or the defaults.
401	The webhook does not exist, is disabled, or the secret is wrong. All three look the same.
404	The project, deployment or agent is not in the webhook’s workspace.
413	The body is larger than 32 KB.
422	The target cannot be used for this action, or the idempotency key was reused with a different body.

A successful response looks like this:

{
  "deliveryId": "whd_…",
  "status": "Accepted",
  "projectId": "prj_…",
  "deploymentId": "dpl_…",
  "taskId": "tsk_…",
  "error": null
}

Senders that cannot set headers

Some notification services only let you enter a URL. For those, put the secret, and the ids the call needs, in the URL and point the service at it. The task text then comes from the webhook’s defaults, and the service’s own message becomes the payload:

https://api.prod.stratonext.com/v1/webhooks/<webhook-id>?deploymentId=<deployment-id>&agentId=<agent-id>&secret=<secret>

Subscription handshakes are handled for you: when a service sends a confirmation request to the URL before it starts delivering, the webhook confirms it, so the subscription goes live without anyone clicking a link.

Tip

This is how to wire a cloud alarm to an agent: subscribe the webhook URL to the alarm’s notification topic, and every state change becomes a task for the agent named on the webhook.

Manage webhooks

From the webhook’s page in workspace settings you can:

• Disable it to refuse calls without deleting it, and enable it again later.
• Rotate the secret. The previous secret stops working at once.
• Edit the name and the defaults: description, instructions, agent, project and deployment.
• See deliveries: each call, when it arrived, what it targeted and what it produced.
• Delete it. Past deliveries and the tasks they created are kept.

Every task a webhook creates shows the webhook as its creator, so you can always tell which calls did what.