The hosted platform is coming soon. Join the waitlist to be notified at launch.

Events

Events represent something that happened in your system. When you create an event, Deliverant creates deliveries to each specified endpoint.

POST/v1/events

Ingest an event and create deliveries to the specified endpoints.

Request body

ParameterTypeDescription

typereq

string

Event type (e.g. order.created)

payloadreq

object

Event payload (max 256KB)

endpoint_idsreq

string[]

List of prefixed endpoint IDs

idempotency_key

string

Key for deduplication (enables RELIABLE mode)

RequestJSON

{
  "type": "order.created",
  "payload": { "order_id": 123, "amount": 99.99 },
  "endpoint_ids": ["ep_550e8400-e29b-41d4-a716-446655440000"],
  "idempotency_key": "unique-key-123"
}

202 ResponseJSON

{
  "event_id": "evt_f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "deliveries": [
    {
      "delivery_id": "del_6ba7b810-9dad-11d1-80b4-00c04fd430c8",
      "endpoint_id": "ep_550e8400-e29b-41d4-a716-446655440000",
      "created": true
    }
  ]
}

Idempotency

Deliverant supports two delivery modes based on whether you provide an idempotency_key:

RELIABLE

When idempotency_key is provided. Deduplication uses the user-supplied key within a 72-hour window.

BASIC

Without an idempotency key. A deterministic key is generated from tenant + endpoint + type + payload hash.

Deduplication Behavior

When a duplicate is detected within the 72-hour window, the existing delivery is returned with "created": false.

If the same idempotency key is reused with a different payload, the API returns 409 Conflict.

409 ResponseJSON

{
  "error": {
    "code": "IDEMPOTENCY_KEY_CONFLICT",
    "message": "Idempotency key reused with different payload",
    "details": {}
  }
}

Endpoints

Deliveries