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