Webhook deliveries

What went out to an endpoint, what waits for a retry and what failed, with the responses of the receiver; a delivery can be retried.

Loading the search index…

Webhook deliveries

Objects

WebhookDelivery

  • idintegerrequired

    ID of the record, unique among records of its kind in the store.

  • endpoint_idintegerrequired

    ID of the webhook endpoint.

  • event_idinteger or nullrequired

    ID of the event in GET /v1/events, the same as webhook-id of the delivery; null for a test event.

  • event_typestringrequired

    Type of the event; ping for a test event.

  • statusstringrequired

    pending — waiting for an attempt; succeeded — the receiver responded 2xx; failed — the retries are exhausted.

    Values:
    pendingsucceededfailed
  • attempt_countintegerrequired

    Attempts made.

  • next_attempt_atstring (date-time) or nullrequired

    When the next attempt goes; null when the delivery is closed.

  • last_attemptobject or null

    The last attempt; null before the first. Only in the list.

    Fields · 7
    • numberintegerrequired

      Number of the attempt, from 1.

    • manualbooleanrequired

      The attempt was made on a retry request, not by the schedule.

    • started_atstring (date-time)required

      When the attempt started.

    • duration_msintegerrequired

      How long the attempt took, in milliseconds.

    • response_statusinteger or nullrequired

      HTTP status the receiver responded with; null when there was no response.

    • response_bodystring or nullrequired

      Beginning of the response body of the receiver; null when there was none.

    • errorstring or nullrequired

      Why the attempt failed; null when the receiver responded 2xx. redirect — a 3xx response, redirects are not followed; http_error — another status; timeout — no response in 10 seconds; tls, connection, dns, unreachable — the network; blocked — the address leads to an internal network; invalid_url — the address does not pass the check.

      Values:
      invalid_urlblockeddnsconnectiontlstimeoutunreachableredirecthttp_errornull
  • attemptsarray of object

    All attempts in order. Only for one delivery.

    Fields · 7
    • numberintegerrequired

      Number of the attempt, from 1.

    • manualbooleanrequired

      The attempt was made on a retry request, not by the schedule.

    • started_atstring (date-time)required

      When the attempt started.

    • duration_msintegerrequired

      How long the attempt took, in milliseconds.

    • response_statusinteger or nullrequired

      HTTP status the receiver responded with; null when there was no response.

    • response_bodystring or nullrequired

      Beginning of the response body of the receiver; null when there was none.

    • errorstring or nullrequired

      Why the attempt failed; null when the receiver responded 2xx. redirect — a 3xx response, redirects are not followed; http_error — another status; timeout — no response in 10 seconds; tls, connection, dns, unreachable — the network; blocked — the address leads to an internal network; invalid_url — the address does not pass the check.

      Values:
      invalid_urlblockeddnsconnectiontlstimeoutunreachableredirecthttp_errornull
  • created_atstring (date-time)required

    When the record was created.

  • updated_atstring (date-time)required

    When the record last changed.

Endpoints

Deliveries of a webhook endpoint: what went out, what awaits a retry, what failed

get/webhook-endpoints/{endpoint}/deliveries

Scope: webhooks:read

Parameters

Path

  • endpointintegerrequired

    ID of the webhook endpoint.

Query

  • limitinteger

    Page size: up to 250 records; 50 by default.

    Minimum:
    1
    Maximum:
    250
  • cursorstring

    Opaque cursor: next_cursor of the previous page, or sync_cursor of the last page saved by the previous sync. The list goes in commit order, so the sync cursor later returns only what changed after it.

    Max length:
    4096
  • updated_sincestring (date-time)

    Only records changed after this moment, ISO 8601 with a time zone. A filter for the first sync; continue with the cursor.

    Pattern:
    ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,6})?(Z|[+-]\d{2}:\d{2})$
  • statusstring

    Only deliveries in this status.

    Values:
    pendingsucceededfailed

Responses

200Success

application/json

  • dataarray of WebhookDeliveryrequired

    Records of the page.

  • deletedarray of objectrequired

    Records erased from the database since the cursor, as tombstones: only with include_deleted=true in the continuation by the sync cursor.

    Fields · 2
    • idintegerrequired

      ID of the erased record.

    • deleted_atstring (date-time)required

      When the record was erased.

  • next_cursorstring or nullrequired

    Cursor of the next page; null on the last page.

  • has_morebooleanrequired

    true when there is a next page.

  • sync_cursorstring or nullrequired

    On the last page — the cursor to continue from later: it returns only what changed after this page. null on other pages.

401The token is missing, invalid, expired or revoked

Headers

  • WWW-Authenticatestringrequired

    Authentication scheme (RFC 6750).

    Example:
    Bearer

application/problem+json

Returns Problem

403The plan, the IP address or the token scopes do not allow the request

Headers

  • WWW-Authenticatestring

    Authentication scheme (RFC 6750).

    Example:
    Bearer error="insufficient_scope", scope="locations:read"

application/problem+json

Returns ForbiddenProblem

404The object does not exist or is not available to the app

application/problem+json

Returns Problem

410The sync cursor is older than the deletion retention period or was issued before the database was restored

application/problem+json

Returns Problem

422A parameter is invalid or unknown

application/problem+json

Returns ValidationProblem

429The rate limit is exhausted

Headers

  • Retry-Afterintegerrequired

    Seconds to wait before retrying.

    Minimum:
    0

application/problem+json

Returns RateLimitProblem

503The store is temporarily unavailable

Headers

  • Retry-Afterinteger

    Seconds to wait before retrying.

    Minimum:
    0

application/problem+json

Returns Problem

Errors of this endpoint

Common errors such as token, access, input validation and rate limit can come from any endpoint; they are listed in the catalog: Errors

Example request
curl "https://api.saleya.app/v1/webhook-endpoints/{endpoint}/deliveries" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN"
Example response · 200
{
  "data": [
    {
      "id": 0,
      "endpoint_id": 0,
      "event_id": 0,
      "event_type": "string",
      "status": "pending",
      "attempt_count": 0,
      "next_attempt_at": "2026-01-15T12:00:00Z",
      "last_attempt": {
        "number": 0,
        "manual": true,
        "started_at": "2026-01-15T12:00:00Z",
        "duration_ms": 0,
        "response_status": 0,
        "response_body": "string",
        "error": "invalid_url"
      },
      "attempts": [
        {
          "number": 0,
          "manual": true,
          "started_at": "2026-01-15T12:00:00Z",
          "duration_ms": 0,
          "response_status": 0,
          "response_body": "string",
          "error": "invalid_url"
        }
      ],
      "created_at": "2026-01-15T12:00:00Z",
      "updated_at": "2026-01-15T12:00:00Z"
    }
  ],
  "deleted": [
    {
      "id": 0,
      "deleted_at": "2026-01-15T12:00:00Z"
    }
  ],
  "next_cursor": "string",
  "has_more": true,
  "sync_cursor": "string"
}

A webhook delivery with all attempts and receiver responses

get/webhook-deliveries/{delivery}

Scope: webhooks:read

Parameters

Path

  • deliveryintegerrequired

    ID of the webhook delivery.

Responses

200Success

application/json

Returns WebhookDelivery

401The token is missing, invalid, expired or revoked

Headers

  • WWW-Authenticatestringrequired

    Authentication scheme (RFC 6750).

    Example:
    Bearer

application/problem+json

Returns Problem

403The plan, the IP address or the token scopes do not allow the request

Headers

  • WWW-Authenticatestring

    Authentication scheme (RFC 6750).

    Example:
    Bearer error="insufficient_scope", scope="locations:read"

application/problem+json

Returns ForbiddenProblem

404The object does not exist or is not available to the app

application/problem+json

Returns Problem

422A parameter is invalid or unknown

application/problem+json

Returns ValidationProblem

429The rate limit is exhausted

Headers

  • Retry-Afterintegerrequired

    Seconds to wait before retrying.

    Minimum:
    0

application/problem+json

Returns RateLimitProblem

503The store is temporarily unavailable

Headers

  • Retry-Afterinteger

    Seconds to wait before retrying.

    Minimum:
    0

application/problem+json

Returns Problem

Common errors such as token, access, input validation and rate limit can come from any endpoint; they are listed in the catalog: Errors

Example request
curl "https://api.saleya.app/v1/webhook-deliveries/{delivery}" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN"
Example response · 200
{
  "id": 0,
  "endpoint_id": 0,
  "event_id": 0,
  "event_type": "string",
  "status": "pending",
  "attempt_count": 0,
  "next_attempt_at": "2026-01-15T12:00:00Z",
  "last_attempt": {
    "number": 0,
    "manual": true,
    "started_at": "2026-01-15T12:00:00Z",
    "duration_ms": 0,
    "response_status": 0,
    "response_body": "string",
    "error": "invalid_url"
  },
  "attempts": [
    {
      "number": 0,
      "manual": true,
      "started_at": "2026-01-15T12:00:00Z",
      "duration_ms": 0,
      "response_status": 0,
      "response_body": "string",
      "error": "invalid_url"
    }
  ],
  "created_at": "2026-01-15T12:00:00Z",
  "updated_at": "2026-01-15T12:00:00Z"
}

Send a ping test event to the endpoint — one attempt signed with the current secret

post/webhook-endpoints/{endpoint}/test

Scope: webhooks:write

Parameters

Path

  • endpointintegerrequired

    ID of the webhook endpoint.

Header

  • Idempotency-Keystring

    Unique key of the attempt, for example a UUID. A retry with the same key and body gets the saved response instead of a second write. Keys live 24 hours.

    Min length:
    1
    Max length:
    255
    Example:
    8e03978e-40d5-43e8-bc93-6894a57f9324

Responses

202Accepted: the outcome is at the Location URL

Headers

  • Idempotent-Replayedstring

    true when this is the saved response of an earlier request with the same Idempotency-Key.

    Values:
    true
  • Locationstring (uri)required

    Address of the created record; for an accepted request (202), the address to follow its outcome.

application/json

Returns WebhookDelivery

401The token is missing, invalid, expired or revoked

Headers

  • WWW-Authenticatestringrequired

    Authentication scheme (RFC 6750).

    Example:
    Bearer

application/problem+json

Returns Problem

403The plan, the IP address or the token scopes do not allow the request

Headers

  • WWW-Authenticatestring

    Authentication scheme (RFC 6750).

    Example:
    Bearer error="insufficient_scope", scope="locations:read"

application/problem+json

Returns ForbiddenProblem

404The object does not exist or is not available to the app

application/problem+json

Returns Problem

409A request with the same idempotency key is in progress, the data changed after it was read, the external ID belongs to another record, the plan or webhook endpoint limit is reached, or the change needs consent to its consequences

Headers

  • Retry-Afterinteger

    Seconds to wait before retrying.

    Minimum:
    0

application/problem+json

Returns ConflictProblem

422A parameter is invalid or unknown

application/problem+json

Returns ValidationProblem

429The rate limit is exhausted

Headers

  • Retry-Afterintegerrequired

    Seconds to wait before retrying.

    Minimum:
    0

application/problem+json

Returns RateLimitProblem

503The store is temporarily unavailable

Headers

  • Retry-Afterinteger

    Seconds to wait before retrying.

    Minimum:
    0

application/problem+json

Returns Problem

Errors of this endpoint

Common errors such as token, access, input validation and rate limit can come from any endpoint; they are listed in the catalog: Errors

Example request
curl -X POST "https://api.saleya.app/v1/webhook-endpoints/{endpoint}/test" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN"
Example response · 202
{
  "id": 0,
  "endpoint_id": 0,
  "event_id": 0,
  "event_type": "string",
  "status": "pending",
  "attempt_count": 0,
  "next_attempt_at": "2026-01-15T12:00:00Z",
  "last_attempt": {
    "number": 0,
    "manual": true,
    "started_at": "2026-01-15T12:00:00Z",
    "duration_ms": 0,
    "response_status": 0,
    "response_body": "string",
    "error": "invalid_url"
  },
  "attempts": [
    {
      "number": 0,
      "manual": true,
      "started_at": "2026-01-15T12:00:00Z",
      "duration_ms": 0,
      "response_status": 0,
      "response_body": "string",
      "error": "invalid_url"
    }
  ],
  "created_at": "2026-01-15T12:00:00Z",
  "updated_at": "2026-01-15T12:00:00Z"
}

Retry the delivery now — the same body and the same webhook-id

post/webhook-deliveries/{delivery}/retry

Scope: webhooks:write

Parameters

Path

  • deliveryintegerrequired

    ID of the webhook delivery.

Header

  • Idempotency-Keystring

    Unique key of the attempt, for example a UUID. A retry with the same key and body gets the saved response instead of a second write. Keys live 24 hours.

    Min length:
    1
    Max length:
    255
    Example:
    8e03978e-40d5-43e8-bc93-6894a57f9324

Responses

202Accepted: the outcome is at the Location URL

Headers

  • Idempotent-Replayedstring

    true when this is the saved response of an earlier request with the same Idempotency-Key.

    Values:
    true
  • Locationstring (uri)required

    Address of the created record; for an accepted request (202), the address to follow its outcome.

application/json

Returns WebhookDelivery

401The token is missing, invalid, expired or revoked

Headers

  • WWW-Authenticatestringrequired

    Authentication scheme (RFC 6750).

    Example:
    Bearer

application/problem+json

Returns Problem

403The plan, the IP address or the token scopes do not allow the request

Headers

  • WWW-Authenticatestring

    Authentication scheme (RFC 6750).

    Example:
    Bearer error="insufficient_scope", scope="locations:read"

application/problem+json

Returns ForbiddenProblem

404The object does not exist or is not available to the app

application/problem+json

Returns Problem

409A request with the same idempotency key is in progress, the data changed after it was read, the external ID belongs to another record, the plan or webhook endpoint limit is reached, or the change needs consent to its consequences

Headers

  • Retry-Afterinteger

    Seconds to wait before retrying.

    Minimum:
    0

application/problem+json

Returns ConflictProblem

422A parameter is invalid or unknown

application/problem+json

Returns ValidationProblem

429The rate limit is exhausted

Headers

  • Retry-Afterintegerrequired

    Seconds to wait before retrying.

    Minimum:
    0

application/problem+json

Returns RateLimitProblem

503The store is temporarily unavailable

Headers

  • Retry-Afterinteger

    Seconds to wait before retrying.

    Minimum:
    0

application/problem+json

Returns Problem

Errors of this endpoint

Common errors such as token, access, input validation and rate limit can come from any endpoint; they are listed in the catalog: Errors

Example request
curl -X POST "https://api.saleya.app/v1/webhook-deliveries/{delivery}/retry" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN"
Example response · 202
{
  "id": 0,
  "endpoint_id": 0,
  "event_id": 0,
  "event_type": "string",
  "status": "pending",
  "attempt_count": 0,
  "next_attempt_at": "2026-01-15T12:00:00Z",
  "last_attempt": {
    "number": 0,
    "manual": true,
    "started_at": "2026-01-15T12:00:00Z",
    "duration_ms": 0,
    "response_status": 0,
    "response_body": "string",
    "error": "invalid_url"
  },
  "attempts": [
    {
      "number": 0,
      "manual": true,
      "started_at": "2026-01-15T12:00:00Z",
      "duration_ms": 0,
      "response_status": 0,
      "response_body": "string",
      "error": "invalid_url"
    }
  ],
  "created_at": "2026-01-15T12:00:00Z",
  "updated_at": "2026-01-15T12:00:00Z"
}