Webhooks

Overview

When a transaction reaches a terminal state (succeeded or failed), winam-payments sends a POST JSON request to your callback_url. A late deposit confirmation (operator SMS/USSD arriving after the transaction expired or failed) does not auto-credit: the transaction first moves to requires_manual_resolution and waits for a Winam operator decision. The webhook is sent only once that decision resolves it to succeeded (payment.succeeded) or failed (payment.failed). See State Machine.

Webhooks are the recommended way to receive payment outcomes — faster and more reliable than polling. Always provide a callback_url in your deposit and withdrawal requests.

Webhook payload

{
  "winam_tx_id":    "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "reference":      "platform-bet-slip-98765",
  "event":          "payment.succeeded",
  "direction":      "deposit",
  "amount_xaf":     5000,
  "operator":       "mtn",
  "provider_tx_id": "MTN2025010112345",
  "ts":             "2025-01-01T12:07:43.123456+00:00"
}

Field	Possible values
`event`	`payment.succeeded` or `payment.failed`
`direction`	`deposit` or `withdrawal`
`provider_tx_id`	Provider-side reference (null if not available)
`ts`	ISO 8601 UTC timestamp of the event

Signature verification

Each webhook includes an X-Winam-Signature header containing a JWT RS256 token signed with Winam’s private key. Always verify this signature before processing the webhook.

Fetch the public key (once)

curl https://api.winampay.de/api/v1/security/callback-public-key

Cache this response — the key rotates rarely.

Verify the signature

import jwt
import httpx

# 1. Fetch the public key (cache this)
r = httpx.get("https://api.winampay.de/api/v1/security/callback-public-key")
public_key = r.json()["public_key_pem"]

# 2. Verify the received webhook
def verify_webhook(request_headers: dict, request_body: dict) -> bool:
    signature = request_headers.get("X-Winam-Signature")
    if not signature:
        return False
    try:
        decoded = jwt.decode(
            signature,
            public_key,
            algorithms=["RS256"],
        )
        return decoded["winam_tx_id"] == request_body["winam_tx_id"]
    except jwt.InvalidTokenError:
        return False

const jwt = require('jsonwebtoken');

function verifyWebhook(headers, body) {
  const signature = headers['x-winam-signature'];
  if (!signature) return false;
  try {
    const decoded = jwt.verify(signature, PUBLIC_KEY_PEM, { algorithms: ['RS256'] });
    return decoded.winam_tx_id === body.winam_tx_id;
  } catch (e) {
    return false;
  }
}

Retry policy

winam-payments retries 3 times with exponential backoff (1 s → 2 s → 4 s) if your endpoint responds with a status ≥ 400 or does not respond within 5 seconds. Your endpoint must:

Respond 2XX within 5 seconds
Be idempotent — the same winam_tx_id may be delivered more than once
Return 200 even if the event was already processed

If all retries fail, no further delivery attempts are made. Use Replay Webhook for manual recovery.

For the public key endpoint reference, see Callback Public Key.

Get Started

Payments

Transactions

Providers

Security

Reference

Overview

Webhook payload

Signature verification

Retry policy

​Overview

​Webhook payload

​Signature verification

​Retry policy

Overview

Webhook payload

Signature verification

Retry policy