Webhook endpoints

Every endpoint below lives under https://sreagent.app and takes a POST. Replace <token> with your organization’s webhook token. You find the token, and a ready-made URL for each source, on Integrations, Webhooks tab.

The token is part of every URL and identifies your organization. Treat the URLs as credentials: anyone holding one can post alerts, deployments and cards into your organization.

Endpoints

Source	Method and path	What it does	Authentication
Grafana	`POST /webhooks/grafana/<token>`	Creates and resolves alerts from a Grafana contact point.	Token. Must be signed once you have an approved runbook that runs automatically.
PagerDuty	`POST /webhooks/pagerduty/<token>`	Mirrors PagerDuty incidents as alerts and keeps acknowledgements and resolves in step.	Token, plus an optional signing secret you save on the Webhooks tab. Must be signed once you have an approved runbook that runs automatically.
Datadog	`POST /webhooks/datadog/<token>`	Creates and resolves alerts from a Datadog monitor webhook.	Token. Must be signed once you have an approved runbook that runs automatically.
New Relic	`POST /webhooks/newrelic/<token>`	Creates and resolves alerts from a New Relic notification channel.	Token. Must be signed once you have an approved runbook that runs automatically.
CloudWatch	`POST /webhooks/cloudwatch/<token>`	Creates and resolves alerts from CloudWatch alarms delivered by an SNS topic. Confirms the SNS subscription for you.	Token, plus AWS’s SNS signature when checking is enabled for your organization.
CloudTrail	`POST /webhooks/cloudtrail/<token>`	Creates alerts from CloudTrail events delivered by an SNS topic. Confirms the SNS subscription for you.	Token, plus AWS’s SNS signature when checking is enabled for your organization.
Deployments	`POST /webhooks/deployments/<token>`	Records a deploy, rollback or other change on the deployments timeline, so alerts can be correlated with it.	Token.
GitHub	`POST /webhooks/github/<token>`	Turns repository events (push, pull request, workflow run, deployment status, release) into timeline entries.	Token, plus an optional signing secret you save on the Webhooks tab. GitHub sends it as `X-Hub-Signature-256`.
Ops board cards	`POST /webhooks/tickets/<token>`	Opens one card in Triage.	Token.
Ops board card updates	`POST /webhooks/tickets/<token>/<card-id or key>`	Edits a card: fields, column, or “won’t do”, which archives it.	Token.
Ops board comments	`POST /webhooks/tickets/<token>/<card-id or key>/comments`	Adds one comment to an open card.	Token.
Jira	`POST /webhooks/jira/<token>`	Keeps a card in step with a Jira issue. An issue labeled `sre-agent-fix` also asks for a fix pull request.	Token.
Zoho Sprints	`POST /webhooks/zoho-sprints/<token>`	Keeps a card in step with a Zoho Sprints item. An item tagged `sre-agent-fix` also asks for a fix pull request.	Token.
Fix requests	`POST /webhooks/fix-requests/<token>`	Asks for a fix in plain words and answers with a draft pull request or a reasoned decline.	Token.

Fix pull requests, including the Jira, Zoho Sprints and fix request routes, need the Business plan and the GitHub App installed. See Plan matrix.

How authentication works

The token in the URL decides which organization receives the request. A token that does not match any organization, or one whose organization is disabled, always gets the same 404 with “Invalid webhook token”, so the endpoint never confirms whether a token exists. Grafana, Datadog, New Relic and PagerDuty alerts must be signed once you have an approved runbook that runs automatically. Requests without a valid signature from those sources then answer 401. You set PagerDuty and GitHub signing secrets under Integrations, Webhooks tab. For Grafana, Datadog and New Relic, contact support to enable signing. Once a PagerDuty or GitHub secret is saved, every request must carry a matching signature or it is refused with 401. Without a saved secret, GitHub accepts requests on the token alone, and the tab shows a warning saying so. CloudWatch and CloudTrail deliver through SNS, which signs its own messages. When signature checking is enabled for your organization, an unsigned message or a direct alarm payload that did not come through SNS is refused.

Rotating the token

Choose Rotate token on the Webhooks tab to get a new URL. The old URL keeps working for 72 hours so you can move your senders over, then answers 404. Revoke now stops the old URL immediately.

Response codes

Code	When you see it
`200`	The request was read. Alert sources answer `{"status":"ok","processed":N,"total":N}`. GitHub answers `200` with `status` set to `ok`, `ignored` or `error` so GitHub does not disable the webhook. A redelivery of a card or comment you already sent also answers `200`.
`201`	An ops board card or comment was created.
`202`	A fix request was accepted and is being analyzed. The outcome arrives later, not in this response.
`400`	The payload could not be read as an alert (alert sources), or an SNS confirmation address was invalid.
`401`	The request is not signed correctly: a signing secret is saved and the signature is missing or wrong, or the request is from Grafana, Datadog, New Relic or PagerDuty, you have an approved runbook that runs automatically, and the request is unsigned.
`403`	Your plan does not include the feature. The ops board answers “The ops board is not included in this plan.”
`404`	The token is wrong, rotated away, or its organization is disabled. On the ops board, also: no card with that id or key on your board.
`413`	The body is too large. See Limits.
`422`	The request was understood but refused. The body names the reason, and on the ops board a `field` to fix.
`429`	You are over a rate limit. See Limits.
`502`	SRE Agent could not confirm an SNS subscription. Ask AWS to send the confirmation again.

A request without a User-Agent header can be refused before it reaches SRE Agent. Set a User-Agent header, or contact support if it persists.

Ops board cards, updates and comments

The three ops board endpoints work on any plan, including Free. A card opened here lands in Triage with no author. Any status, source or author you send on create is ignored.

Open a card

curl -X POST https://sreagent.app/webhooks/tickets/<token> \
  -H 'content-type: application/json' \
  -d '{
    "title": "Checkout latency is climbing again",
    "description": "Third night in a row, p99 above 2s from 22:00.",
    "priority": "high",
    "labels": ["checkout", "latency"],
    "service": "checkout"
  }'

Only title is required. A 201 answers with the card’s id, its key (for example OPS-12) and its url. priority is one of urgent, high, normal or low, and any other value becomes normal. assignee_email assigns the card when it matches a member of your organization and never invites anyone. Field sizes are on Limits.

Update a card or add a comment

Use either the card id or its key in the path. The key is matched without regard to case, and only within your organization.

curl -X POST https://sreagent.app/webhooks/tickets/<token>/OPS-12 \
  -H 'content-type: application/json' \
  -d '{"status": "in progress", "priority": "urgent"}'

curl -X POST https://sreagent.app/webhooks/tickets/<token>/OPS-12/comments \
  -H 'content-type: application/json' \
  -d '{"body": "Reader came back up at 11:40.", "author": "Ana"}'

An update sends only the fields you want to change. status is one of backlog, triage, todo, in_progress, blocked or done, and the usual synonyms work. won't do, wontfix and cancelled archive the card without counting it as done. An unknown status or priority on update answers 422 rather than guessing. A comment needs a body. author is a display name shown beside it and is not matched against your members.

Idempotency keys

Without a key, every POST opens a new card, and a sender that retries creates duplicates. To make a delivery safe to repeat, send your own id for it. A card accepts the id as an Idempotency-Key header or a dedup_key field in the body. If both are present, the header wins. When the body is an SNS notification, its message id is used automatically. A comment takes comment_id. The first delivery answers 201. Every repeat answers 200 with the same body and "duplicate": true, and nothing else happens: no second card, notification or Slack post. A key is up to 200 characters of letters, digits and . _ - : / + = @. Anything else, including a blank key, answers 422. Keys belong to your organization and never expire, so use a new key when you mean a new card.

Card endpoint responses

Code	Body or meaning
`201`	`{"id":"<uuid>","key":"OPS-12","url":"...","dedup_key":null,"duplicate":false}` for a new card. A comment answers `{"id":"<uuid>"}`.
`200`	A card update (`id`, `key`, `status`, `url`), or a repeat of a delivery you already sent.
`403`	The ops board is not included in this plan.
`404`	Invalid webhook token, or “No such card on this board.” A card on another organization’s board answers the same as a card that does not exist.
`413`	The body is larger than 65,536 bytes.
`422`	No title or body, a wrong field type, a bad key, or an unknown status or priority.
`429`	”Rate limit exceeded. Retry in Ns.” with a `retry-after` header.

Deployments

curl -X POST https://sreagent.app/webhooks/deployments/<token> \
  -H 'content-type: application/json' \
  -d '{
    "service": "checkout",
    "environment": "production",
    "event_type": "deploy",
    "version": "v1.42.0",
    "status": "succeeded",
    "dedup_key": "ci-run-8123"
  }'

event_type defaults to deploy and status to succeeded. You can also send previous_version, deployed_by, description, commit_sha, repo_full_name, pr_url, compare_url, run_url, branch, author, started_at and completed_at. Posting the same dedup_key again, for example from the start and the end of one CI run, updates the same timeline entry. A success answers 200 with {"status":"ok","id":"...","action":"..."}, and a payload that cannot be recorded answers 422.

Fix requests

curl -X POST https://sreagent.app/webhooks/fix-requests/<token> \
  -H 'content-type: application/json' \
  -d '{
    "description": "grant the deploy role read on the artifacts bucket",
    "service": "checkout",
    "dedup_key": "workflow-run-8123"
  }'

Only description is required. service or repo pins the target repository. Sending the same dedup_key or ticket again replaces the earlier request instead of opening a second pull request. A 202 with {"status":"analyzing","id":"..."} means the request was queued, not that a pull request will follow. The result, a draft pull request or a decline with reasoning, appears in Control Tower. A 422 means it was refused before analysis, with a reason such as the GitHub App not being installed, a target that matches nothing you mapped, or five open pull requests already on that repository.

Jira

Jira answers 200 for an issue it accepts and for one it ignores, so Jira does not disable the webhook over a configuration problem. {"status":"ok"} means a fix pull request is being generated. {"status":"ignored"} carries the reason: the issue has no sre-agent-fix label, the GitHub App is not installed, the target matches nothing you mapped, or the repository is at its limit of open pull requests. A wrong token answers 404, and a payload with no summary answers 422.

Quickstart: send a first test alert.
Connect PagerDuty: set up the PagerDuty signing secret.
Ops board webhook and tracker sync: use the ops board webhook step by step.
Troubleshooting: fix a failing webhook.

Get started

Respond to incidents

Fix

Prevent

Security and cost

Administer

Reference

Endpoints

How authentication works

Rotating the token

Response codes

Ops board cards, updates and comments

Open a card

Update a card or add a comment

Idempotency keys

Card endpoint responses

Deployments

Fix requests

Jira

​Endpoints

​How authentication works

​Rotating the token

​Response codes

​Ops board cards, updates and comments

​Open a card

​Update a card or add a comment

​Idempotency keys

​Card endpoint responses

​Deployments

​Fix requests

​Jira

​Related

Endpoints

How authentication works

Rotating the token

Response codes

Ops board cards, updates and comments

Open a card

Update a card or add a comment

Idempotency keys

Card endpoint responses

Deployments

Fix requests

Jira

Related