Quickstart · 5 minute guide

Send your first delivery

Create an event delivery, receive its identifier, and confirm that Relayline has queued it for your destination.

Reading time: About 5 minutes
Authentication: Bearer API key
Success response: 202 Accepted

Before you start

The workflow requires an HTTPS endpoint that can receive JSON and an API key. Requests and responses below illustrate the contract using example URLs, not a live API.

Command line access with curl installed
A Relayline test API key
An HTTPS destination that accepts POST requests

Step 1

Store your API key

The examples read the key from an environment variable. For a real key in an interactive Bash session, use a silent prompt so you do not type the secret into a command that may be saved in shell history.

Terminalbash

read -r -s -p "Relayline API key: " RELAYLINE_API_KEY
printf '\n'
export RELAYLINE_API_KEY

Step 2

Create a delivery

Send a POST request with the destination, event name, and JSON payload.

POST/v1/deliveries

Requestcurl

curl --request POST \
  https://api.relayline.example/v1/deliveries \
  --header "Authorization: Bearer $RELAYLINE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "destination": "https://example.com/webhooks/orders",
    "event": "order.created",
    "payload": {
      "order_id": "ord_7M2L9",
      "total": 4800,
      "currency": "USD"
    },
    "idempotency_key": "order-7M2L9-created"
  }'

Step 3

Inspect the response

Relayline returns 202 Accepted after validating and queueing the delivery. Save the id to inspect its status later.

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
}

First delivery queued

You have authenticated, submitted a valid event, and received a delivery identifier.

Create a delivery with Node.js

Use the built-in fetch API in Node.js 18 or later. Check the response status before reading the delivery so API errors do not pass silently.

Complete requestJavaScript

const response = await fetch(
  'https://api.relayline.example/v1/deliveries',
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.RELAYLINE_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      destination: 'https://example.com/webhooks/orders',
      event: 'order.created',
      payload: { order_id: 'ord_7M2L9', total: 4800, currency: 'USD' },
      idempotency_key: 'order-7M2L9-created',
    }),
  },
);

if (!response.ok) {
  const problem = await response.json();
  throw new Error(`${problem.error.code}: ${problem.error.message}`);
}

const delivery = await response.json();
console.log(delivery.id, delivery.status);

Step 4

Confirm delivery

A queued response confirms that Relayline accepted the request. Retrieve the delivery to determine whether the destination received it.

Retrieve deliverycurl

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"
}

What if the destination fails?

Follow the delivery recovery walkthrough from 202 Accepted through a destination 503, an automatic retry, and confirmed receipt. It shows the requests, responses, and receiver changes in one sequence, including what to do when retries run out.