API reference

Deliveries

A delivery represents one event queued for an HTTPS destination. Use the resource identifier to inspect attempts and final status.

Base URL: https://api.relayline.example
Authentication: Bearer <API_KEY>
Content type: application/json

POST/v1/deliveries

Create a delivery

Validates an event and adds it to the delivery queue. A successful response confirms acceptance, not receipt by the destination.

Request headers

Header	Required	Description
`Authorization`	Yes	A bearer API key for the target environment.
`Content-Type`	Yes	Must be `application/json`.

Request body

Field	Type	Required	Description
`destination`	string (URI)	Yes	An HTTPS URL that accepts the event.
`event`	string	Yes	A lowercase event name of 1–80 characters. Separators can be periods, underscores, or hyphens.
`payload`	object	Yes	The JSON object sent to the destination. Maximum serialized size: 256 KB.
`idempotency_key`	string	No	A 1–120 character key that prevents duplicate delivery creation for 24 hours.

Request bodyjson

{
  "destination": "https://example.com/webhooks/orders",
  "event": "order.created",
  "payload": {
    "order_id": "ord_7M2L9",
    "total": 4800,
    "currency": "USD"
  },
  "idempotency_key": "order-7M2L9-created"
}

Response

Returns 202 Accepted with the queued delivery. The Relayline-Request-Id response header identifies the API request.

Response · 202 Acceptedjson

{
  "id": "dlv_01J6Y3G8V9K2M4P7Q1R5",
  "event": "order.created",
  "status": "queued",
  "destination": "https://example.com/webhooks/orders",
  "attempts": 0,
  "created_at": "2026-09-04T14:32:18Z",
  "completed_at": null
}

Status	Meaning
`202`	The delivery was validated and queued.
`400`	The request body is missing a required field or contains an invalid value.
`401`	The API key is missing or invalid.
`409`	The idempotency key was used with different request data.
`429`	The project exceeded its request limit.

GET/v1/deliveries/{delivery_id}

Retrieve a delivery

Returns the delivery’s current state, attempt count, and completion time.

Path parameter

Parameter	Type	Description
`delivery_id`	string	The identifier returned when the delivery was created.

Requestcurl

curl https://api.relayline.example/v1/deliveries/dlv_01J6Y3G8V9K2M4P7Q1R5 \
  --header "Authorization: Bearer $RELAYLINE_API_KEY"

Response · 200 OKjson

{
  "id": "dlv_01J6Y3G8V9K2M4P7Q1R5",
  "event": "order.created",
  "status": "delivered",
  "destination": "https://example.com/webhooks/orders",
  "attempts": 1,
  "created_at": "2026-09-04T14:32:18Z",
  "completed_at": "2026-09-04T14:32:19Z"
}

GET/v1/deliveries

List deliveries

Returns deliveries for the authenticated project in reverse chronological order. Use a cursor to continue through older results.

Query parameters

Parameter	Type	Default	Description
`status`	string	All	Return only `queued`, `retrying`, `delivered`, or `failed` deliveries.
`limit`	integer	`20`	Number of results to return, from 1 through 100.
`cursor`	string	Not required	The opaque `next_cursor` value from the previous response.

Requestcurl

curl \
  "https://api.relayline.example/v1/deliveries?status=failed&limit=20" \
  --header "Authorization: Bearer $RELAYLINE_API_KEY"

Response · 200 OKjson

{
  "data": [
    {
      "id": "dlv_01J6Y3G8V9K2M4P7Q1R5",
      "event": "order.created",
      "status": "failed",
      "destination": "https://example.com/webhooks/orders",
      "attempts": 5,
      "created_at": "2026-09-04T14:32:18Z",
      "completed_at": "2026-09-04T17:08:21Z"
    }
  ],
  "next_cursor": "dlv_01J6XZZZZZZZZZZZZZZZ"
}

When next_cursor is null, there are no more results. Treat cursor values as opaque and do not construct or modify them.

Delivery object

Field	Type	Description
`id`	string	Opaque delivery identifier beginning with `dlv_`.
`event`	string	The event name supplied when the delivery was created.
`status`	string	`queued`, `retrying`, `delivered`, or `failed`.
`destination`	string (URI)	The HTTPS destination receiving the event.
`attempts`	integer	The number of HTTP delivery attempts already made, from 0 through 5.
`created_at`	string (date-time)	When the delivery was accepted, in UTC.
`completed_at`	string or null	When the delivery entered a terminal state, or `null` while work continues.

Errors and limits

All errors use one response envelope with a stable code and request identifier. See Errors and rate limits for resolution steps, response headers, and a bounded retry example.