Webhooks

Overview

A Feddi event reports a domain change that already committed: a wallet balance moved, a top-up settled, a promotional grant accrued. Each event carries a stable event_id you dedup on and a signature you verify before you trust the body. Webhooks are server-to-server deliveries: Feddi makes an HTTP POST to your endpoint with the event envelope in the body and the signature in a header. The envelope and signature contract is stable to build against now, even before outbound delivery is mounted. This page is the contract you build your receiver against: the event catalog, the event envelope, and the signature-verification steps. All are stable. Build your verifier now, validate it against your own test vectors, and you are ready to receive deliveries the moment they are available to you.

Outbound delivery endpoints are not yet mounted. Until they ship, reconcile settled activity through the transactions read API at Transactions. The envelope and signature contract on this page is what you verify when delivery becomes available, so you can write the receiver against it today.

The event envelope

Every event carries the same envelope. Process each event idempotently on its event_id: the same event can arrive more than once, so dedup before you act.

required

Globally unique. This is your idempotency key for processing. Store it, and treat a second arrival of the same event_id as a no-op.

required

The domain change, for example wallet.balance_changed, topup.confirmed, or promo_grant.accrued. Branch your handler on this value.

required

RFC3339 timestamp of when the underlying domain change happened.

required

RFC3339 timestamp of when Feddi emitted the event, always after the database transaction committed. An event never precedes the change it describes.

required

The Feddi merchant tenant this event belongs to.

required

The event-type-specific payload. Read the fields your handler needs by event_type.

{
  "event_id": "evt_9b2c41",
  "event_type": "topup.confirmed",
  "occurred_at": "2026-06-05T10:14:55Z",
  "emitted_at": "2026-06-05T10:14:55Z",
  "merchant_id": "11111111-1111-1111-1111-111111111111",
  "data": { "wallet_id": "wal_77", "credited_actual_minor": 5000, "currency": "QAR" }
}

Money inside data always follows the same shape: a minor-units integer paired with an explicit ISO-4217 currency, for example credited_actual_minor: 5000 with currency: QAR.

Event catalog

These are the event types Feddi emits, grouped by domain, with when each one fires.

Identity & enrollment

event_type	When it fires
`customer.identified`	A known wallet is resolved at the POS.
`customer.enrolled`	A new customer is created.
`enrollment.pending_proof`	A credit lands for an unverified customer and is held.
`enrollment.verified`	Phone proof completes; held promo releases.
`enrollment.expired`	A pending-proof window lapses.

Money & wallet

event_type	When it fires
`wallet.balance_changed`	Any balance delta.
`topup.requested`	A top-up is requested.
`topup.confirmed`	A top-up settled and credited.
`topup.failed`	A top-up did not settle.
`payment.completed`	A wallet debit landed.
`payment.refunded`	A wallet payment was refunded.
`payment.reversed`	A wallet payment was reversed.

Promotion & incentive

event_type	When it fires
`promo_grant.accrued`	A promotional grant accrued.
`promo_grant.released`	A held promotional grant released.
`promo_grant.expired`	A promotional grant expired.
`promo_grant.clawed_back`	A promotional grant was clawed back.
`offer.armed`	An offer is armed for a customer.
`offer.redeemed`	An offer is redeemed.
`offer.expired`	An offer expires unredeemed.

Lifecycle & reconciliation

event_type	When it fires
`transaction.settled`	A transaction settled.
`transaction.disputed`	A transaction is disputed.
`transaction.unattached`	A previously attached receipt or transaction is detached from a customer.

Every payload follows the same envelope; branch your handler on event_type and read the fields your handler needs.

Delivery model

How deliveries behave on the wire, so your receiver tolerates the realities of an at-least-once channel.

At-least-once delivery. The same event can arrive more than once. Dedup on event_id.
Per-resource ordering. A monotonic sequence_number on the envelope orders events within a single resource. Do not assume global order across resources.
Retry with backoff. Any non-2xx response or timeout is retried with exponential backoff, then dead-lettered after retries are exhausted.
Replay window. The signed timestamp enforces a replay window. Reject anything outside it before you read the body.
Idempotent processing. Key your processing on event_id so a redelivery is a no-op.
Endpoint auto-disable. Sustained delivery failure auto-disables the endpoint. Re-enable it from the dashboard.

The delivery sequence:

Subscriptions

This is a forward contract, not yet mounted. When delivery ships, you will:

Register a delivery endpoint URL per integration.
Receive a per-subscription signing secret.
List and disable subscriptions.
Rotate the signing secret.

Until then, reconcile through the transactions read API.

Verify every delivery

Feddi signs each delivery with HMAC-SHA256 over a canonical base string, keyed by your subscription secret. Verify the signature and reject anything outside the replay window before you read the body. An unsigned or stale request is not a Feddi event. The signature travels in the Feddi-Signature header as t=<unix-timestamp>,v1=<hex-hmac>. The signing base string is the signed timestamp, a literal ., then the exact raw request body:

signing_base = "<timestamp>.<raw-json-body>"
signature    = HMAC_SHA256(secret, signing_base)   // lowercase hex

Read the header

Parse Feddi-Signature. Take t (the signed Unix timestamp) and v1 (the expected hex signature).

Reject stale timestamps

If t is outside your replay window (compare against your own clock), reject the request. This is what stops a captured payload from being replayed against you later. We recommend a tolerance of 300 seconds or less.

Recompute and compare

Build t + "." + raw_body, compute HMAC-SHA256 with your stored secret, and compare to v1 using a constant-time equality check. Sign the raw bytes you received, never a re-serialized object: any whitespace or key-order change breaks the match.

Process idempotently, then 2xx

On a match inside the window, dedup on event_id, act, and return a 2xx. A non-2xx response (or a timeout) signals failure to Feddi.

import hashlib
import hmac
import time

def verify(headers, raw_body: bytes, secret: str, tolerance_s: int = 300) -> bool:
    parts = dict(p.split("=", 1) for p in headers["Feddi-Signature"].split(","))
    timestamp, provided = parts["t"], parts["v1"]

    if abs(time.time() - int(timestamp)) > tolerance_s:
        return False  # outside the replay window

    signing_base = f"{timestamp}.".encode() + raw_body
    expected = hmac.new(secret.encode(), signing_base, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, provided)  # constant-time

{
  "ok": false,
  "data": null,
  "error": {
    "code": "INVALID_SIGNATURE",
    "message": "Signature did not match or timestamp is outside the replay window."
  },
  "meta": { "request_id": "req_evt1", "api_version": "2026-06-01" }
}

Compare with a constant-time function (hmac.compare_digest in Python, crypto.timingSafeEqual in Node). A plain string equality check leaks timing information that can be used to forge a signature.

Show Why sign the raw body, not the parsed object

HMAC is computed over exact bytes. If you parse the JSON and re-serialize it before signing, your byte stream will differ from what Feddi signed (whitespace, key ordering, numeric formatting), and the comparison fails on a legitimate event. Capture the raw request body before any JSON middleware touches it, and feed those bytes to the verifier.

Reconcile through the transactions read API

Until delivery endpoints are available, treat the transactions read API as your source of truth for what settled. Poll it on a schedule, or pull it on demand to confirm an order reconciled.

List with GET /{integrationId}/transactions, cursor-paginated and filterable by status, a date window, and branch_id.
Read one with GET /{integrationId}/transactions/{transactionId}.

Both reads are tenant-scoped to the integration in the path and your x-api-key. A mismatched {integrationId} resolves to 401 or 403, never another tenant’s rows. See Transactions for the full projection fields each read returns.

Where to go next

Transactions

The settlement reads you reconcile against today, with their full projection fields.

Idempotency & errors

Dedup on event_id the same way you key mutating calls, and handle every typed error code.

Conventions

The response envelope, money-as-minor-units, and the meta block on every response.

Authentication

The x-api-key your reconciliation reads authenticate with.

Get started

Core concepts

Guides

Overview

The event envelope

Event catalog

Identity & enrollment

Money & wallet

Promotion & incentive

Lifecycle & reconciliation

Delivery model

Subscriptions

Verify every delivery

Reconcile through the transactions read API

Where to go next

Transactions

Idempotency & errors

Conventions

Authentication

​Overview

​The event envelope

​Event catalog

​Identity & enrollment

​Money & wallet

​Promotion & incentive

​Lifecycle & reconciliation

​Delivery model

​Subscriptions

​Verify every delivery

​Reconcile through the transactions read API

​Where to go next

Transactions

Idempotency & errors

Conventions

Authentication

Overview

The event envelope

Event catalog

Identity & enrollment

Money & wallet

Promotion & incentive

Lifecycle & reconciliation

Delivery model

Subscriptions

Verify every delivery

Reconcile through the transactions read API

Where to go next