Safestate
Partner API

List failed webhook deliveries

GET
/api/v1/integrations/webhooks/failures

Query Parameters

page?integer

Page number (1-based)

Default1
Range1 <= value
pageSize?integer

Number of records per page (max 100)

Default20
Range1 <= value <= 100
eventType?string

Filter by canonical event type (e.g. customer.breach.found)

from?string

Inclusive lower bound on failure time (ISO 8601 date-time with offset)

Formatdate-time
to?string

Inclusive upper bound on failure time (ISO 8601 date-time with offset)

Formatdate-time

Header Parameters

SW-PARTNER-ID*string

Partner organization identifier

SW-API-KEY*string

API authentication key for the partner

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/api/v1/integrations/webhooks/failures" \  -H "SW-PARTNER-ID: string" \  -H "SW-API-KEY: string"
{
  "success": true,
  "failures": [
    {
      "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "eventType": "customer.breach.found",
      "targetUrl": "https://example.com/webhooks/safeweb",
      "idempotencyToken": "8f2c1b0e-9a3d-4f5e-b6c7-d8e9f0a1b2c3",
      "payload": {
        "customer": {
          "uuid": "550e8400-e29b-41d4-a716-446655440000",
          "name": "Acme Ltd",
          "reference": "ACME-001"
        },
        "breaches": [
          {
            "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "name": "LinkedIn-2024",
            "emails": [
              "user@example.com"
            ]
          }
        ]
      },
      "failedAt": "2026-06-20T14:32:11.000Z",
      "httpStatus": 503,
      "responseIndicator": null,
      "attempts": [
        {
          "id": "11111111-2222-4333-8444-555555555555",
          "attemptedAt": "2026-06-20T14:31:45.000Z",
          "httpStatus": 503,
          "responseIndicator": null,
          "errorMessage": "Failed to send webhook(503): Service Unavailable"
        },
        {
          "id": "22222222-3333-4444-8555-666666666666",
          "attemptedAt": "2026-06-20T14:32:11.000Z",
          "httpStatus": 503,
          "responseIndicator": null,
          "errorMessage": "Failed to send webhook(503): Service Unavailable"
        }
      ]
    }
  ],
  "pagination": {
    "totalCount": 1,
    "page": 1,
    "pageSize": 20,
    "hasNextPage": false
  }
}
{
  "success": false,
  "error": "pageSize: Too big: expected number to be <=100"
}
{
  "success": false,
  "error": "string"
}
{
  "success": false,
  "error": "string"
}
{
  "success": false,
  "error": "string"
}

When to use this endpoint

Use this endpoint to audit and debug webhook delivery problems. Each record represents one logical event that exhausted all retry attempts without a successful delivery. Records include:

  • The event type and target URL that failed
  • The outbound payload (data from the delivery envelope) exactly as SafeWeb attempted to send it
  • Every delivery attempt, with HTTP status codes or timeout/network/signature indicators
  • A total count in the pagination envelope so you can gauge overall failure volume

Failed delivery records are retained for at least 30 days before automatic expiry.

Supported event types

Failure records use the same canonical eventType values as outbound deliveries. See Outbound webhooks — Event types for the full catalogue:

eventTypeWhen it fires
customer.createdA new customer record exists for the org.
customer.deletedA customer was removed / offboarded.
customer.asset.addedOne or more domains or emails were added to monitoring.
customer.asset.removedAssets were removed.
customer.breach.foundNew breach rows were detected for the customer.
customer.breach.firstscan.completedA customer's first breach scan finished.
customer.breach.resolvedBreach(es) transitioned to resolved.
customer.breach.unresolvedBreach(es) transitioned back to unresolved.

Filter results with the eventType query parameter.

Response indicators

When your server does not return an HTTP status (or the connection fails before a response is received), httpStatus is null and responseIndicator is set:

responseIndicatorMeaning
timeoutNo complete HTTP response within the 3 second delivery timeout.
network_errorTransport-level failure before a response was received.
invalid_signatureYour server returned 2xx but the response X-Signature header did not verify.

Worked example

List the first page of failures from the last seven days, then filter to breach events:

# 1. List recent failures (default page size 20, newest first)
curl -sS "https://connect.safestate.com/api/v1/integrations/webhooks/failures?from=2026-06-15T00:00:00.000Z" \
  -H "SW-PARTNER-ID: your-partner-id" \
  -H "SW-API-KEY: your-api-key" | jq .

# 2. Filter to breach.found events with a smaller page
curl -sS "https://connect.safestate.com/api/v1/integrations/webhooks/failures?eventType=customer.breach.found&pageSize=10" \
  -H "SW-PARTNER-ID: your-partner-id" \
  -H "SW-API-KEY: your-api-key" | jq .

# 3. Paginate when hasNextPage is true
curl -sS "https://connect.safestate.com/api/v1/integrations/webhooks/failures?page=2&pageSize=10" \
  -H "SW-PARTNER-ID: your-partner-id" \
  -H "SW-API-KEY: your-api-key" | jq .

Example success response (truncated):

{
  "success": true,
  "failures": [
    {
      "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "eventType": "customer.breach.found",
      "targetUrl": "https://example.com/webhooks/safeweb",
      "idempotencyToken": "8f2c1b0e-9a3d-4f5e-b6c7-d8e9f0a1b2c3",
      "payload": {
        "partnerId": "22222222-2222-4222-8222-222222222222",
        "customer": { "uuid": "550e8400-e29b-41d4-a716-446655440000" },
        "breaches": [
          {
            "uuid": "a1b2…",
            "name": "LinkedIn-2024",
            "emails": ["user@example.com"]
          }
        ]
      },
      "failedAt": "2026-06-20T14:32:11.000Z",
      "httpStatus": 503,
      "responseIndicator": null,
      "attempts": [
        {
          "id": "11111111-2222-4333-8444-555555555555",
          "attemptedAt": "2026-06-20T14:32:11.000Z",
          "httpStatus": 503,
          "responseIndicator": null,
          "errorMessage": "Failed to send webhook(503): Service Unavailable"
        }
      ]
    }
  ],
  "pagination": {
    "totalCount": 1,
    "page": 1,
    "pageSize": 20,
    "hasNextPage": false
  }
}

Query parameters

ParameterTypeDefaultDescription
pageinteger1Page number (1-based).
pageSizeinteger20Records per page (max 100).
eventTypestring—Filter to a single event type (e.g. customer.created).
fromISO 8601—Inclusive lower bound on failedAt.
toISO 8601—Inclusive upper bound on failedAt.

Results are ordered by most recent failure first (failedAt descending).

Delete a webhook endpoint DELETE

Permanently removes a webhook endpoint. The endpoint must belong to the authenticated partner organization.

Generate webhook signing secret POST

Creates a new active signing secret for the authenticated partner organization when none exists. The token is returned once; store it securely and use it to verify `X-Signature` on deliveries. There is no request body.