Notifex

Developer docs

Integrate your app with Notifex — trigger notifications, receive provider callbacks, and understand how flows route messages.

Authentication

Server-to-server requests are authenticated with an API key, sent as the x-api-key header.

Create a key from your console under Settings → API Keys. The full key is shown once, at creation — store it securely.

Keys are shown in your console as e.g. nf_live_9k2a7c1f… — treat the whole string as an opaque secret.

curl https://api.notifex.dev/api/v1/notifications/notify \
  -H "x-api-key: nf_live_9k2a7c1f…" \
  -H "Content-Type: application/json"

Trigger a notification

Send a message through one of your flows.

Request

POST /notifications/notify
x-api-key: nf_live_9k2a7c1f…
Content-Type: application/json

{
  "flow_key": "payment-receipt",
  "recipient": "+2250700000000",
  "message": {
    "text": "Your payment of 12,000 XOF was received.",
    "subject": "Payment received",
    "title": "Receipt",
    "image_url": "https://cdn.example.com/receipt.png"
  }
}

Body fields

  • flow_key — the flow's key (letters, digits, - or _, 2-100 chars).
  • recipient — destination address or number, 1-500 chars.
  • message.text — message body, required, 1-4096 chars.
  • message.subject — optional.
  • message.title — optional.
  • message.image_url — optional.

Response

202 Accepted

{
  "execution_id": "8f3c1a2e-4b0e-4d7a-9c2f-1e6b0a7d5f21"
}

202 Accepted — the notification is queued, not yet delivered. Use the execution id to poll status.

Check delivery status

GET /notifications/{execution_id}/status
x-api-key: nf_live_9k2a7c1f…

Poll this endpoint until status leaves queued or processing.

Status values: queued, processing, sent, failed, delivered, undelivered.

Errors

  • 401 — missing or invalid API key.
  • 404 — execution id not found.

Provider callback webhook

This is not a webhook Notifex sends to your app. It's the inbound URL your own notification provider (e.g. Twilio, SendGrid) calls back into Notifex on, so Notifex can update delivery status for messages it routed through that provider.

Where to find it

On the Providers page, each connected provider card shows a webhook URL and a secret (owner role only). The secret is shown once, at connection time.

Setup

Paste the webhook URL into your provider's own dashboard (its delivery-status callback setting) and store the secret there if the provider supports callback verification. Notifex does not send this webhook to your servers — it only receives it from your provider.

Flows & fallback

A flow is an ordered pipeline of steps. Each step targets one channel and one provider; triggering a flow by its key walks the steps in order.

Step fields

  • position — order within the flow.
  • channel — one of sms, email, whatsapp, push.
  • provider_code — which connected provider handles this step.
  • max_attempts — retry attempts for this step, 1-6.
  • retry_delays_sec — seconds to wait between each attempt.
  • is_fallback — when true, this step only runs after a prior step for the same channel exhausts its attempts.
Developer docs — Notifex