Event Ingestion: Submit Events & Confirm Delivery

Event Ingestion

SendPromptly uses a single ingestion endpoint for transactional notification events.

Endpoint: POST /v1/events

Required headers

Authorization: Bearer sp_{env}_{token}
Idempotency-Key: <unique-key>
Content-Type: application/json

Minimal request

1
2
3
4
5
{
  "event_key": "order.created",
  "recipient": { "email": "[email protected]" },
  "payload": { "order_id": "O-100023" }
}

Field guidance

Field	Required	Guidance
`event_key`	Yes	Use durable domain names, for example `invoice.failed` or `shipment.delivered`.
`recipient`	Yes	Include addressing data needed for your target channels.
`payload`	Yes	Keep stable contracts and avoid frequent shape changes.
`schedule_at`	No	Set when a notification should be delivered later.

Ingestion behavior

Validates authentication, payload shape, and required data.
Enforces idempotency (24-hour TTL) so safe retries do not duplicate work.
Resolves active templates by event_key and environment.
Creates delivery runs for enabled channels (email, webhook).

Success and error handling

A successful request returns 201 with accepted event metadata. Validation and auth issues return 4xx errors with actionable codes. Rate and transient errors should be retried with exponential backoff and jitter.

Idempotency strategy

Use a deterministic key derived from your business event id, for example order-100023-created. Reuse the same key when retrying the same event payload.

Integration checklist

Validate payload schema before sending.
Normalize event_key naming across services.
Add ingestion metrics by event key and environment.
Monitor error codes and retry outcomes in delivery logs.