Alert sources

Download schema

External tools that fire and resolve alerts in Spectate: Prometheus Alertmanager, Grafana, Sentry, email, or your own scripts through a webhook. Each source has its own secret URL (and email address); its alerts follow its escalation paths.

List alert sources

GET

https://api.spectate.net/v1

/alert-sources

Returns the team's alert sources, by name.

List alert sources › query Parameters

filter[type]

AlertSourceProvider · enum

Only sources of this tool.

The external tool behind an alert source; decides how its requests are read.


`webhook` Spectate's own JSON format, for scripts, CI and anything that can call a URL.
`email` Emails to the source's own address (subject becomes the alert).
`alertmanager` Prometheus Alertmanager `webhook_configs`.
`grafana` Grafana Alerting webhook contact point (Alertmanager format plus Grafana links).
`sentry` Sentry internal integration webhooks (SaaS and self-hosted), or the legacy WebHooks plugin.

Enum values:

webhook

alertmanager

grafana

sentry

page

integer

Page number, from 1.

Default: 1

per_page

integer

Sources per page, 1 to 100.

Default: 25

List alert sources › Responses

Paginated set of AlertSource

current_page

integer · min: 1 · required

AlertSource[] · required

first_page_url

string | null · required

from

integer | null · min: 1 · required

last_page_url

string | null · required

last_page

integer · min: 1 · required

object[] · required

Generated paginator links.

next_page_url

string | null · required

path

string | null · required

Base path for paginator generated URLs.

per_page

integer · min: 0 · required

Number of items shown per page.

prev_page_url

string | null · required

to

integer | null · min: 1 · required

Number of the last item in the slice.

total

integer · min: 0 · required

Total number of items being paginated.

GET/alert-sources

curl https://api.spectate.net/v1/alert-sources \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "current_page": 1,
  "data": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "name": "Production Alertmanager",
      "type": "webhook",
      "enabled": true,
      "webhook_url": "https://www.example.com/path/to/resource",
      "email_address": "test@example.com",
      "has_secret": true,
      "default_severity": "critical",
      "auto_resolve_minutes": 60,
      "settings": {
        "alert_on_new_issues": true,
        "signature_header": "X-Grafana-Alerting-Signature",
        "timestamp_header": "timestamp_header"
      },
      "project_id": "00000000-0000-0000-0000-000000000000",
      "escalation_paths": [
        {
          "id": "00000000-0000-0000-0000-000000000000",
          "name": "On-call engineers"
        }
      ],
      "last_event_at": "2024-08-25T15:00:00Z",
      "events_count": 0,
      "firing_alerts_count": 0,
      "created_at": "2024-08-25T15:00:00Z"
    }
  ],
  "first_page_url": "first_page_url",
  "from": 1,
  "last_page_url": "last_page_url",
  "last_page": 1,
  "links": [
    {
      "url": "url",
      "label": "label",
      "active": true
    }
  ],
  "next_page_url": "next_page_url",
  "path": "path",
  "per_page": 0,
  "prev_page_url": "prev_page_url",
  "to": 1,
  "total": 0
}

json

application/json

Create an alert source

POST

https://api.spectate.net/v1

/alert-sources

Returns the source with its webhook_url (and email_address for email) to set up in the tool. Email sources resolve alerts after an hour without a repeat unless auto_resolve_minutes says otherwise: mail has no "resolved".

Create an alert source › Request Body

A new alert source. The response has the `webhook_url` (and `email_address`) to configure in the tool.

CreateAlertSource

name

string · maxLength: 255 · required

Name shown on its alerts, up to 255 characters

Example: Production Alertmanager

type

AlertSourceProvider · enum · required

The tool that will send requests


`webhook` Spectate's own JSON format, for scripts, CI and anything that can call a URL.
`email` Emails to the source's own address (subject becomes the alert).
`alertmanager` Prometheus Alertmanager `webhook_configs`.
`grafana` Grafana Alerting webhook contact point (Alertmanager format plus Grafana links).
`sentry` Sentry internal integration webhooks (SaaS and self-hosted), or the legacy WebHooks plugin.

Enum values:

webhook

alertmanager

grafana

sentry

default_severity

Severity · enum

Severity of alerts sent without one. Default high


`critical` Customers are affected right now.
`high` Serious, needs attention soon.
`medium` Should be looked at.
`low` Informational.

Enum values:

critical

high

medium

low

auto_resolve_minutes

integer | null · min: 5 · max: 10080

Minutes, 5 to 10080, after which an alert the tool stopped repeating resolves; null keeps it until resolved. Default null, or 60 for email sources

secret

string | null · maxLength: 255

Signing secret the tool uses: Sentry client secret, Grafana HMAC secret or Alertmanager bearer token. Write-only

AlertSourceSettingsInput

Type-specific settings

project_id

string | null · uuid

Project whose escalation paths apply when the source has none of its own

escalation_path_ids

string[] · unique

Escalation paths for the source's alerts

Create an alert source › Responses

The new alert source.

An alert source: an external tool (Prometheus Alertmanager, Grafana, Sentry, a script…) whose requests to `webhook_url`, or mails to `email_address`, fire and resolve alerts. The URL and address contain the source's secret token: whoever has them can fire alerts.

AlertSource

id

string · uuid · required

Alert source ID

name

string · required

Name shown on its alerts

Example: Production Alertmanager

type

AlertSourceProvider · enum · required

The tool, which decides how requests are read


`webhook` Spectate's own JSON format, for scripts, CI and anything that can call a URL.
`email` Emails to the source's own address (subject becomes the alert).
`alertmanager` Prometheus Alertmanager `webhook_configs`.
`grafana` Grafana Alerting webhook contact point (Alertmanager format plus Grafana links).
`sentry` Sentry internal integration webhooks (SaaS and self-hosted), or the legacy WebHooks plugin.

Enum values:

webhook

alertmanager

grafana

sentry

enabled

boolean · required

Whether requests fire alerts; a disabled source rejects them

webhook_url

string · uri · required

Where the tool sends its webhooks. Secret: rotate it with rotateAlertSourceToken if it leaks

email_address

string | null · email · required

email sources: the address to send mails to. Secret like the URL

has_secret

boolean · required

Whether a signing secret is set (Sentry client secret, Grafana HMAC secret, Alertmanager bearer token); it's never returned

default_severity

Severity · enum · required

Severity of alerts the tool sends without one


`critical` Customers are affected right now.
`high` Serious, needs attention soon.
`medium` Should be looked at.
`low` Informational.

Enum values:

critical

high

medium

low

auto_resolve_minutes

integer | null · required

Minutes after which an alert the tool stopped repeating resolves; null keeps it until the tool resolves it

Example: 60

AlertSourceSettings · required

Type-specific settings

project_id

string | null · uuid · required

The project whose escalation paths apply when the source has none of its own; null for none

EscalationPathReference[] · required

Escalation paths the source's alerts follow. Empty: the project's paths, else the team's default path

last_event_at

string | null · date-time · required

When the source last received a request

events_count

integer · required

Requests the source has received in total

firing_alerts_count

integer · required

Alerts of the source that are firing now

created_at

string · date-time · required

When the source was created

POST/alert-sources

curl https://api.spectate.net/v1/alert-sources \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "name": "Production Alertmanager",
  "type": "webhook",
  "default_severity": "critical",
  "auto_resolve_minutes": 5,
  "secret": "secret",
  "settings": {
    "alert_on_new_issues": true,
    "signature_header": "X-Grafana-Alerting-Signature",
    "timestamp_header": "timestamp_header"
  },
  "project_id": "00000000-0000-0000-0000-000000000000",
  "escalation_path_ids": [
    "00000000-0000-0000-0000-000000000000"
  ]
}'

Example Request Body

{
  "name": "Production Alertmanager",
  "type": "webhook",
  "default_severity": "critical",
  "auto_resolve_minutes": 5,
  "secret": "secret",
  "settings": {
    "alert_on_new_issues": true,
    "signature_header": "X-Grafana-Alerting-Signature",
    "timestamp_header": "timestamp_header"
  },
  "project_id": "00000000-0000-0000-0000-000000000000",
  "escalation_path_ids": [
    "00000000-0000-0000-0000-000000000000"
  ]
}

json

Example Responses

{
  "id": "00000000-0000-0000-0000-000000000000",
  "name": "Production Alertmanager",
  "type": "webhook",
  "enabled": true,
  "webhook_url": "https://www.example.com/path/to/resource",
  "email_address": "test@example.com",
  "has_secret": true,
  "default_severity": "critical",
  "auto_resolve_minutes": 60,
  "settings": {
    "alert_on_new_issues": true,
    "signature_header": "X-Grafana-Alerting-Signature",
    "timestamp_header": "timestamp_header"
  },
  "project_id": "00000000-0000-0000-0000-000000000000",
  "escalation_paths": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "name": "On-call engineers"
    }
  ],
  "last_event_at": "2024-08-25T15:00:00Z",
  "events_count": 0,
  "firing_alerts_count": 0,
  "created_at": "2024-08-25T15:00:00Z"
}

json

application/json

Get an alert source

GET

https://api.spectate.net/v1

/alert-sources/{source}

Returns the source with its URL and how many of its alerts are firing.

Get an alert source › path Parameters

source

string · uuid · required

Alert source ID.

Get an alert source › Responses

The alert source.

AlertSource

id

string · uuid · required

Alert source ID

name

string · required

Name shown on its alerts

Example: Production Alertmanager

type

AlertSourceProvider · enum · required

The tool, which decides how requests are read


`webhook` Spectate's own JSON format, for scripts, CI and anything that can call a URL.
`email` Emails to the source's own address (subject becomes the alert).
`alertmanager` Prometheus Alertmanager `webhook_configs`.
`grafana` Grafana Alerting webhook contact point (Alertmanager format plus Grafana links).
`sentry` Sentry internal integration webhooks (SaaS and self-hosted), or the legacy WebHooks plugin.

Enum values:

webhook

alertmanager

grafana

sentry

enabled

boolean · required

Whether requests fire alerts; a disabled source rejects them

webhook_url

string · uri · required

Where the tool sends its webhooks. Secret: rotate it with rotateAlertSourceToken if it leaks

email_address

string | null · email · required

email sources: the address to send mails to. Secret like the URL

has_secret

boolean · required

Whether a signing secret is set (Sentry client secret, Grafana HMAC secret, Alertmanager bearer token); it's never returned

default_severity

Severity · enum · required

Severity of alerts the tool sends without one


`critical` Customers are affected right now.
`high` Serious, needs attention soon.
`medium` Should be looked at.
`low` Informational.

Enum values:

critical

high

medium

low

auto_resolve_minutes

integer | null · required

Minutes after which an alert the tool stopped repeating resolves; null keeps it until the tool resolves it

Example: 60

AlertSourceSettings · required

Type-specific settings

project_id

string | null · uuid · required

The project whose escalation paths apply when the source has none of its own; null for none

EscalationPathReference[] · required

Escalation paths the source's alerts follow. Empty: the project's paths, else the team's default path

last_event_at

string | null · date-time · required

When the source last received a request

events_count

integer · required

Requests the source has received in total

firing_alerts_count

integer · required

Alerts of the source that are firing now

created_at

string · date-time · required

When the source was created

GET/alert-sources/{source}

curl https://api.spectate.net/v1/alert-sources/:source \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "id": "00000000-0000-0000-0000-000000000000",
  "name": "Production Alertmanager",
  "type": "webhook",
  "enabled": true,
  "webhook_url": "https://www.example.com/path/to/resource",
  "email_address": "test@example.com",
  "has_secret": true,
  "default_severity": "critical",
  "auto_resolve_minutes": 60,
  "settings": {
    "alert_on_new_issues": true,
    "signature_header": "X-Grafana-Alerting-Signature",
    "timestamp_header": "timestamp_header"
  },
  "project_id": "00000000-0000-0000-0000-000000000000",
  "escalation_paths": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "name": "On-call engineers"
    }
  ],
  "last_event_at": "2024-08-25T15:00:00Z",
  "events_count": 0,
  "firing_alerts_count": 0,
  "created_at": "2024-08-25T15:00:00Z"
}

json

application/json

Update an alert source

PATCH

https://api.spectate.net/v1

/alert-sources/{source}

Changes only the fields you send; settings merge into the current settings.

Update an alert source › path Parameters

source

string · uuid · required

Alert source ID.

Update an alert source › Request Body

Changes to an alert source; fields you leave out keep their value. Its type can't change.

UpdateAlertSource

name

string · maxLength: 255

Name shown on its alerts

Example: Production Alertmanager

enabled

boolean

Whether requests fire alerts

default_severity

Severity · enum

Severity of alerts sent without one


`critical` Customers are affected right now.
`high` Serious, needs attention soon.
`medium` Should be looked at.
`low` Informational.

Enum values:

critical

high

medium

low

auto_resolve_minutes

integer | null · min: 5 · max: 10080

Minutes, 5 to 10080, after which an alert the tool stopped repeating resolves; null keeps it until resolved

secret

string | null · maxLength: 255

Signing secret; an empty string or null removes it. Write-only

AlertSourceSettingsInput

Type-specific settings; settings you leave out keep their value

project_id

string | null · uuid

Project whose escalation paths apply; null for none

escalation_path_ids

string[] · unique

Escalation paths for the source's alerts; replaces the current ones

Update an alert source › Responses

The updated alert source.

AlertSource

id

string · uuid · required

Alert source ID

name

string · required

Name shown on its alerts

Example: Production Alertmanager

type

AlertSourceProvider · enum · required

The tool, which decides how requests are read


`webhook` Spectate's own JSON format, for scripts, CI and anything that can call a URL.
`email` Emails to the source's own address (subject becomes the alert).
`alertmanager` Prometheus Alertmanager `webhook_configs`.
`grafana` Grafana Alerting webhook contact point (Alertmanager format plus Grafana links).
`sentry` Sentry internal integration webhooks (SaaS and self-hosted), or the legacy WebHooks plugin.

Enum values:

webhook

alertmanager

grafana

sentry

enabled

boolean · required

Whether requests fire alerts; a disabled source rejects them

webhook_url

string · uri · required

Where the tool sends its webhooks. Secret: rotate it with rotateAlertSourceToken if it leaks

email_address

string | null · email · required

email sources: the address to send mails to. Secret like the URL

has_secret

boolean · required

Whether a signing secret is set (Sentry client secret, Grafana HMAC secret, Alertmanager bearer token); it's never returned

default_severity

Severity · enum · required

Severity of alerts the tool sends without one


`critical` Customers are affected right now.
`high` Serious, needs attention soon.
`medium` Should be looked at.
`low` Informational.

Enum values:

critical

high

medium

low

auto_resolve_minutes

integer | null · required

Minutes after which an alert the tool stopped repeating resolves; null keeps it until the tool resolves it

Example: 60

AlertSourceSettings · required

Type-specific settings

project_id

string | null · uuid · required

The project whose escalation paths apply when the source has none of its own; null for none

EscalationPathReference[] · required

Escalation paths the source's alerts follow. Empty: the project's paths, else the team's default path

last_event_at

string | null · date-time · required

When the source last received a request

events_count

integer · required

Requests the source has received in total

firing_alerts_count

integer · required

Alerts of the source that are firing now

created_at

string · date-time · required

When the source was created

PATCH/alert-sources/{source}

curl https://api.spectate.net/v1/alert-sources/:source \
  --request PATCH \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "name": "Production Alertmanager",
  "enabled": true,
  "default_severity": "critical",
  "auto_resolve_minutes": 5,
  "secret": "secret",
  "settings": {
    "alert_on_new_issues": true,
    "signature_header": "X-Grafana-Alerting-Signature",
    "timestamp_header": "timestamp_header"
  },
  "project_id": "00000000-0000-0000-0000-000000000000",
  "escalation_path_ids": [
    "00000000-0000-0000-0000-000000000000"
  ]
}'

Example Request Body

{
  "name": "Production Alertmanager",
  "enabled": true,
  "default_severity": "critical",
  "auto_resolve_minutes": 5,
  "secret": "secret",
  "settings": {
    "alert_on_new_issues": true,
    "signature_header": "X-Grafana-Alerting-Signature",
    "timestamp_header": "timestamp_header"
  },
  "project_id": "00000000-0000-0000-0000-000000000000",
  "escalation_path_ids": [
    "00000000-0000-0000-0000-000000000000"
  ]
}

json

Example Responses

{
  "id": "00000000-0000-0000-0000-000000000000",
  "name": "Production Alertmanager",
  "type": "webhook",
  "enabled": true,
  "webhook_url": "https://www.example.com/path/to/resource",
  "email_address": "test@example.com",
  "has_secret": true,
  "default_severity": "critical",
  "auto_resolve_minutes": 60,
  "settings": {
    "alert_on_new_issues": true,
    "signature_header": "X-Grafana-Alerting-Signature",
    "timestamp_header": "timestamp_header"
  },
  "project_id": "00000000-0000-0000-0000-000000000000",
  "escalation_paths": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "name": "On-call engineers"
    }
  ],
  "last_event_at": "2024-08-25T15:00:00Z",
  "events_count": 0,
  "firing_alerts_count": 0,
  "created_at": "2024-08-25T15:00:00Z"
}

json

application/json

Delete an alert source

DELETE

https://api.spectate.net/v1

/alert-sources/{source}

Its firing alerts are resolved first; its URL and address stop working at once.

Delete an alert source › path Parameters

source

string · uuid · required

Alert source ID.

Delete an alert source › Responses

No content

No data returned

Rotate the source's URL

POST

https://api.spectate.net/v1

/alert-sources/{source}/rotate-token

Gives the source a new secret webhook_url (and email_address); the old ones stop working at once, so update the tool right after.

Rotate the source's URL › path Parameters

source

string · uuid · required

Alert source ID.

Rotate the source's URL › Responses

The source with its new URL.

AlertSource

id

string · uuid · required

Alert source ID

name

string · required

Name shown on its alerts

Example: Production Alertmanager

type

AlertSourceProvider · enum · required

The tool, which decides how requests are read


`webhook` Spectate's own JSON format, for scripts, CI and anything that can call a URL.
`email` Emails to the source's own address (subject becomes the alert).
`alertmanager` Prometheus Alertmanager `webhook_configs`.
`grafana` Grafana Alerting webhook contact point (Alertmanager format plus Grafana links).
`sentry` Sentry internal integration webhooks (SaaS and self-hosted), or the legacy WebHooks plugin.

Enum values:

webhook

alertmanager

grafana

sentry

enabled

boolean · required

Whether requests fire alerts; a disabled source rejects them

webhook_url

string · uri · required

Where the tool sends its webhooks. Secret: rotate it with rotateAlertSourceToken if it leaks

email_address

string | null · email · required

email sources: the address to send mails to. Secret like the URL

has_secret

boolean · required

Whether a signing secret is set (Sentry client secret, Grafana HMAC secret, Alertmanager bearer token); it's never returned

default_severity

Severity · enum · required

Severity of alerts the tool sends without one


`critical` Customers are affected right now.
`high` Serious, needs attention soon.
`medium` Should be looked at.
`low` Informational.

Enum values:

critical

high

medium

low

auto_resolve_minutes

integer | null · required

Minutes after which an alert the tool stopped repeating resolves; null keeps it until the tool resolves it

Example: 60

AlertSourceSettings · required

Type-specific settings

project_id

string | null · uuid · required

The project whose escalation paths apply when the source has none of its own; null for none

EscalationPathReference[] · required

Escalation paths the source's alerts follow. Empty: the project's paths, else the team's default path

last_event_at

string | null · date-time · required

When the source last received a request

events_count

integer · required

Requests the source has received in total

firing_alerts_count

integer · required

Alerts of the source that are firing now

created_at

string · date-time · required

When the source was created

POST/alert-sources/{source}/rotate-token

curl https://api.spectate.net/v1/alert-sources/:source/rotate-token \
  --request POST \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "id": "00000000-0000-0000-0000-000000000000",
  "name": "Production Alertmanager",
  "type": "webhook",
  "enabled": true,
  "webhook_url": "https://www.example.com/path/to/resource",
  "email_address": "test@example.com",
  "has_secret": true,
  "default_severity": "critical",
  "auto_resolve_minutes": 60,
  "settings": {
    "alert_on_new_issues": true,
    "signature_header": "X-Grafana-Alerting-Signature",
    "timestamp_header": "timestamp_header"
  },
  "project_id": "00000000-0000-0000-0000-000000000000",
  "escalation_paths": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "name": "On-call engineers"
    }
  ],
  "last_event_at": "2024-08-25T15:00:00Z",
  "events_count": 0,
  "firing_alerts_count": 0,
  "created_at": "2024-08-25T15:00:00Z"
}

json

application/json

Fire a test alert

POST

https://api.spectate.net/v1

/alert-sources/{source}/test

Fires an alert on the source that escalates like a real one (it notifies people) and resolves itself after a few minutes. Returns the event it made.

Fire a test alert › path Parameters

source

string · uuid · required

Alert source ID.

Fire a test alert › Responses

The test event.

A request an alert source received, kept for 7 days.

AlertSourceEvent

id

string · uuid · required

Event ID

received_at

string · date-time · required

When the request arrived

outcome

AlertSourceEventOutcome · enum · required

What became of it


`fired` It fired at least one new alert.
`resolved` It resolved at least one alert.
`updated` It repeated alerts that were already firing.
`test` A test request from the tool's own "test" button; no alert.
`ignored` Valid, but nothing to do (for example a resolve of an alert that isn't firing).
`rejected` Refused: bad signature, unreadable payload or a disabled source; see `error`.

Enum values:

fired

resolved

updated

test

ignored

rejected

summary

string | null · required

What happened, in words

Example: 2 alerts fired

error

string | null · required

Why it was rejected, with outcome rejected

AlertSourceEventAlert[] · required

What it did per alert

object | null · required

The request body as received: the tool's JSON, or {body, truncated} for mail and non-JSON bodies. Its shape is the tool's

List a source's events

GET

https://api.spectate.net/v1

/alert-sources/{source}/events

Returns the requests the source received in the last 7 days, newest first, with what each did. Use it to check that a tool reaches Spectate.

List a source's events › path Parameters

source

string · uuid · required

Alert source ID.

List a source's events › query Parameters

page

integer

Page number, from 1.

Default: 1

per_page

integer

Events per page, 1 to 100.

Default: 25

List a source's events › Responses

Paginated set of AlertSourceEvent

current_page

integer · min: 1 · required

AlertSourceEvent[] · required

first_page_url

string | null · required

from

integer | null · min: 1 · required

last_page_url

string | null · required

last_page

integer · min: 1 · required

object[] · required

Generated paginator links.

next_page_url

string | null · required

path

string | null · required

Base path for paginator generated URLs.

per_page

integer · min: 0 · required

Number of items shown per page.

prev_page_url

string | null · required

to

integer | null · min: 1 · required

Number of the last item in the slice.

total

integer · min: 0 · required

Total number of items being paginated.

GET/alert-sources/{source}/events

curl https://api.spectate.net/v1/alert-sources/:source/events \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "current_page": 1,
  "data": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "received_at": "2024-08-25T15:00:00Z",
      "outcome": "fired",
      "summary": "2 alerts fired",
      "error": "error",
      "alerts": [
        {
          "action": "fired",
          "title": "HighErrorRate",
          "dedupe_key": "4c3d9a…",
          "alert_id": "00000000-0000-0000-0000-000000000000"
        }
      ],
      "payload": {
        "key": {}
      }
    }
  ],
  "first_page_url": "first_page_url",
  "from": 1,
  "last_page_url": "last_page_url",
  "last_page": 1,
  "links": [
    {
      "url": "url",
      "label": "label",
      "active": true
    }
  ],
  "next_page_url": "next_page_url",
  "path": "path",
  "per_page": 0,
  "prev_page_url": "prev_page_url",
  "to": 1,
  "total": 0
}

json

application/json

Escalation paths Alerts