List alert deliveries

GET

/v1/alert-deliveries

curl --request GET \
  --url 'https://api.us.headerhawk.com/v1/alert-deliveries?limit=50' \
  --header 'Authorization: Bearer <token>'

• Production, United States

Every alert HeaderHawk sent, tried to send or dropped, newest first, one entry per destination. A destination is named by its id, name and type, never its address.

Authorizations

• apiKey

Parameters

Query Parameters

siteId

string format: uuid

Only deliveries about this site, digests that covered it included. A site your tenant does not have is 404.

destinationId

string

>= 1 characters <= 64 characters

Only deliveries to this destination, by the id a delivery names it with.

eventType

string

>= 1 characters <= 64 characters

Only alerts of this type, such as csp.new_issue.

limit

integer

default: 50 >= 1 <= 200

How many items a page holds.

cursor

string

>= 1 characters <= 1024 characters

The previous page’s nextCursor. Omit it for the first page.

Responses

200

A page of deliveries

Media typeapplication/json

object

data

required

Array<object>

object

id

required

string

alertId

required

Shared by every destination one alert went to.

string

kind

required

An open enum.

string

Allowed values: immediate digest test

outcome

required

delivered, rejected (it errored or was refused; detail says why), or dropped (there was nothing to send it to). An open enum.

string

Allowed values: delivered rejected dropped

detail

required

Why it was rejected or dropped, such as Webhook failed: 404. Every URL, token, host name and address in it is replaced, so it says what kind of failure it was and never where the destination is.

string

nullable

destination

required

object

id

required

string

name

required

Its name when it was sent; null when the destination was deleted before it could be, which is recorded as dropped.

string

nullable

type

required

email, webhook or slack; null with name.

string

nullable

eventType

required

string

nullable

siteId

required

string

nullable

siteIds

required

The sites a digest covered.

Array<string>

summary

required

The alert’s one-line summary; null for a test, a digest, and alerts from before summaries were recorded.

string

nullable

createdAt

required

string format: date-time

nextCursor

required

string

nullable

Example

{
  "data": [
    {
      "kind": "immediate",
      "outcome": "delivered"
    }
  ]
}

Headers

RateLimit-Limit

integer

The budget nearest to running out, per minute.

RateLimit-Remaining

integer

What is left of that budget this minute.

RateLimit-Reset

integer

Seconds until that budget starts again.

400

A parameter was refused, or one the operation does not take was sent. The message names it.

Media typeapplication/json

object

error

required

object

code

required

What went wrong. An open enum: treat a code you do not know by its HTTP status.

string

Allowed values: bad_request validation_error invalid_api_key plan_upgrade_required forbidden not_found rate_limited rate_limit_unavailable upstream_unavailable internal_error

message

required

For people. Branch on code.

string

requestId

required

Quote it when you write to us about this request.

string

Example

{
  "error": {
    "code": "bad_request"
  }
}

401

invalid_api_key: no key, or one that is malformed, unknown, revoked or expired. One answer for all of them.

Media typeapplication/json

object

error

required

object

code

required

What went wrong. An open enum: treat a code you do not know by its HTTP status.

string

Allowed values: bad_request validation_error invalid_api_key plan_upgrade_required forbidden not_found rate_limited rate_limit_unavailable upstream_unavailable internal_error

message

required

For people. Branch on code.

string

requestId

required

Quote it when you write to us about this request.

string

Example

{
  "error": {
    "code": "bad_request"
  }
}

403

plan_upgrade_required: the tenant’s plan does not include API access (the key works again when it does), or does not include what this operation reads.

Media typeapplication/json

object

error

required

object

code

required

What went wrong. An open enum: treat a code you do not know by its HTTP status.

string

Allowed values: bad_request validation_error invalid_api_key plan_upgrade_required forbidden not_found rate_limited rate_limit_unavailable upstream_unavailable internal_error

message

required

For people. Branch on code.

string

requestId

required

Quote it when you write to us about this request.

string

Example

{
  "error": {
    "code": "bad_request"
  }
}

404

No such resource in your tenant.

Media typeapplication/json

object

error

required

object

code

required

What went wrong. An open enum: treat a code you do not know by its HTTP status.

string

Allowed values: bad_request validation_error invalid_api_key plan_upgrade_required forbidden not_found rate_limited rate_limit_unavailable upstream_unavailable internal_error

message

required

For people. Branch on code.

string

requestId

required

Quote it when you write to us about this request.

string

Example

{
  "error": {
    "code": "bad_request"
  }
}

429

rate_limited: over a budget. Wait Retry-After seconds.

Media typeapplication/json

object

error

required

object

code

required

What went wrong. An open enum: treat a code you do not know by its HTTP status.

string

Allowed values: bad_request validation_error invalid_api_key plan_upgrade_required forbidden not_found rate_limited rate_limit_unavailable upstream_unavailable internal_error

message

required

For people. Branch on code.

string

requestId

required

Quote it when you write to us about this request.

string

Example

{
  "error": {
    "code": "bad_request"
  }
}

Headers

Retry-After

integer

Seconds to wait before trying again.