Webhooks

Webhooks allow KryptaPay to notify your application in real time when events occur on your account. Instead of continuously polling the API for transaction updates, you can register a webhook endpoint and receive notifications automatically when payins, payouts, and conversions change status.

How Webhooks Work

Webhook endpoints are configured from the KryptaPay Dashboard. When creating a webhook endpoint, you provide:

The HTTPS URL where KryptaPay will send events.
The list of events you want to subscribe to.
The environment (sandbox or live) this endpoint applies to.

A signing secret is generated automatically and shown once in the response — store it immediately, it cannot be retrieved again afterward. Once configured, KryptaPay sends an HTTP POST request to your endpoint whenever a subscribed event occurs on a transaction matching your endpoint’s environment.

KryptaPay
     │
     │ Transaction Event
     ▼
Webhook Endpoint
     │
     │ Verify Signature
     ▼
Your Application
     │
     │ Process Event
     ▼
Update Your Records

Creating a Webhook Endpoint

To create a webhook endpoint:

Open the KryptaPay Dashboard.
Navigate to Developers → Webhooks.
Click Create Endpoint.
Enter your HTTPS endpoint URL.
Select the events you want to receive.
Choose the environment — sandbox or live.
Save the endpoint.

The signing secret (whsec_...) is generated by KryptaPay and displayed once, immediately after creation. It is not user-provided and cannot be changed — if it’s lost, delete the endpoint and create a new one.

Webhook endpoints are strongly recommended to use HTTPS. Plaintext HTTP is currently accepted by the API but is not recommended: the payload and signature travel in clear text over the network.

An endpoint only receives events from transactions in the same environment. A sandbox endpoint never receives live events, and vice versa. This mirrors the sandbox/live isolation of your API keys.

Webhook Request

KryptaPay sends events using HTTP POST requests. Example:

POST https://example.com/webhooks/kryptapay
Content-Type: application/json
X-KryptaPay-Signature: 8f4c7d8a2b9e1f6c3d0a5b7e9c2f4a1d6b8e0c3f5a7d9b1e4c6f8a0d2b5e7c9f
X-KryptaPay-Event: PAYOUT_COMPLETED
X-KryptaPay-Event-Id: evt_3k9dQwErTyUiOpAsDfGh

Request body:

{
  "event_id": "evt_...",
  "event_type": "PAYOUT_COMPLETED",
  "created_at": "...",
  "data": {
    "transaction_id": "tx...",
    "reference": "...",
    "amount": "300",
    "currency": "XOF",
    "network": "MTN_BJ",
    "status": "COMPLETED"
  }
}

Authenticating Webhooks

Every webhook request contains a signature in the:

X-KryptaPay-Signature

header. The signature is generated using:

Algorithm: HMAC SHA-256
Secret: The endpoint’s signing secret (whsec_...), shown once when the endpoint was created.
Payload: The raw HTTP request body, exactly as sent (a hex digest of HMAC-SHA256(secret, raw_body)).

Unlike some providers, the header contains the raw hex digest only — there is no sha256= prefix to strip. The event type and event ID are also available directly as headers (X-KryptaPay-Event, X-KryptaPay-Event-Id), so you don’t need to parse the body just to route the event.

Verifying the Signature

Your application must verify the signature before processing the event.

Example (Node.js)

import crypto from "crypto";

function verifyWebhookSignature(rawBody, signature, secret) {
  const expectedSignature = crypto
    .createHmac("sha256", secret)
    .update(rawBody, "utf8")
    .digest("hex");

  const a = Buffer.from(signature, "hex");
  const b = Buffer.from(expectedSignature, "hex");
  if (a.length !== b.length) return false;

  return crypto.timingSafeEqual(a, b);
}

Example usage:

const isValid = verifyWebhookSignature(
  request.rawBody,
  request.headers["x-kryptapay-signature"],
  process.env.WEBHOOK_SECRET
);

if (!isValid) {
  return response.status(401).send({
    error: "Invalid signature"
  });
}

Always verify the signature using the raw request body. Parsing and re-serializing JSON can change the payload (key order, whitespace, number formatting) and cause signature verification to fail even for a legitimate event.

Supported Events

Event	Description
`PAYIN_CREATED`	A new payin (deposit) has been created and is pending or processing.
`PAYIN_RECEIVED`	The payin was successfully received and credited.
`PAYIN_FAILED`	The payin failed.
`PAYOUT_CREATED`	A new payout has been created and is awaiting execution.
`PAYOUT_COMPLETED`	The payout was successfully executed.
`PAYOUT_FAILED`	The payout failed.
`CONVERSION_COMPLETED`	A currency conversion between two of your wallets completed.

There is no intermediate “processing” event for payins or payouts today — you’ll receive *_CREATED at creation, then a terminal *_RECEIVED/*_COMPLETED/*_FAILED event once the transaction settles.

Event payload fields

The data object’s fields depend on the event type:

Event	Fields in `data`
`PAYIN_CREATED`, `PAYIN_RECEIVED`	`transaction_id`, `reference`, `amount`, `currency`, `network`, `status`, `provider_ref`
`PAYIN_FAILED`	Same as above, plus `failure_reason`
`PAYOUT_CREATED`	`transaction_id`, `reference`, `amount`, `currency`, `network`, `status`
`PAYOUT_COMPLETED`	`transaction_id`, `reference`, `amount`, `currency`, `network`, `status`, `provider_ref`
`PAYOUT_FAILED`	Same as `PAYOUT_COMPLETED`, plus `failure_reason`
`CONVERSION_COMPLETED`	`transaction_id`, `reference`, `from_currency`, `to_currency`, `from_amount`, `to_amount`, `status`

amount/from_amount/to_amount are decimal strings (e.g. "10000" or "150.50"), not minor units.

Handling Webhook Events

After verifying the signature:

Check event_type (or the X-KryptaPay-Event header) to route the event.
Retrieve the transaction via data.transaction_id or data.reference if you need more detail than the payload carries.
Update your internal records.
Return a 2xx response.

Example:

switch (event.event_type) {
  case "PAYIN_RECEIVED":
    await fulfillOrder(event.data);
    break;

  case "PAYOUT_COMPLETED":
    await updatePayoutStatus(event.data);
    break;
}

Response Requirements

Your webhook endpoint must respond quickly and with a 2xx status code. Successful response:

HTTP/1.1 200 OK

{
  "received": true
}

The response body isn’t inspected — only the HTTP status code matters. Your endpoint has 10 seconds to respond before the delivery attempt is considered failed. If your endpoint returns anything other than a 2xx status, or doesn’t respond in time, KryptaPay will retry the delivery.

Retry Policy

Delivery is retried on any non-2xx response, a timeout, or a network error, using this schedule:

Attempt	Delay after previous attempt
1	Immediate
2	1 minute
3	5 minutes
4	30 minutes
5	2 hours
6	6 hours

After the 6th failed attempt (roughly 9 hours after the first), delivery is marked as given up and no further retries are made. You can review recent delivery attempts (status, response code, timestamps) for each endpoint from the Dashboard. Your webhook handler should therefore be:

Idempotent — use event_id to detect and skip events you’ve already processed, since retries (and rare duplicate deliveries) resend the same event_id.
Fast — do the minimum synchronously, offload heavier work to a background job.
Safe to execute multiple times.

Best Practices

Always verify X-KryptaPay-Signature using the raw request body.
Store processed event_ids to prevent double-processing on retries.
Return a 2xx status within 10 seconds of receiving the event.
Process heavy tasks asynchronously, after acknowledging the webhook.
Use HTTPS endpoints only.
Log event_id and event_type for debugging.
Do not expose your webhook secret client-side or commit it to source control.

Next Steps

Verification and Compliance

Learn how KryptaPay uses KYB and KYC verification to provide secure, transparent, and trusted payment services.

Getting Started

Resources

Webhooks

Webhooks

How Webhooks Work

Creating a Webhook Endpoint

Webhook Request

Authenticating Webhooks

Verifying the Signature

Example (Node.js)

Supported Events

Event payload fields

Handling Webhook Events

Response Requirements

Retry Policy

Best Practices

Next Steps

Verification and Compliance

​Webhooks

​How Webhooks Work

​Creating a Webhook Endpoint

​Webhook Request

​Authenticating Webhooks

​Verifying the Signature

​Example (Node.js)

​Supported Events

​Event payload fields

​Handling Webhook Events

​Response Requirements

​Retry Policy

​Best Practices

​Next Steps

Verification and Compliance

Webhooks

How Webhooks Work

Creating a Webhook Endpoint

Webhook Request

Authenticating Webhooks

Verifying the Signature

Example (Node.js)

Supported Events

Event payload fields

Handling Webhook Events

Response Requirements

Retry Policy

Best Practices

Next Steps