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 deposits, payouts, and other payment events 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.
A webhook secret used to authenticate requests.

Once configured, KryptaPay sends an HTTP POST request to your endpoint whenever a subscribed event occurs.

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.
Generate or provide a webhook secret.
Save the endpoint.

After creation, KryptaPay will use this endpoint to deliver event notifications.

Webhook endpoints must use HTTPS in production environments.

Webhook Request

KryptaPay sends events using HTTP POST requests. Example:

POST https://example.com/webhooks/kryptapay
Content-Type: application/json
X-KryptaPay-Signature: sha256=8f4c7d8a2b...

Request body:

{
  "id": "evt_01JAB8Y7X9",
  "event": "deposit.completed",
  "created_at": "2026-07-25T15:30:00Z",
  "data": {
    "id": "dep_01JAB5EZQ8Q8Y9T8QTH6B6V2XZ",
    "reference": "ORDER-12345",
    "status": "successful",
    "amount": 10000,
    "currency": "XOF"
  }
}

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 webhook secret configured when the endpoint was created.
Payload: The raw HTTP request body.

The signature format is:

sha256=<signature>

Verifying the Signature

Your application must verify the signature before processing the event.

Example (Node.js)

import crypto from "crypto";

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

  return crypto.timingSafeEqual(
    Buffer.from(signature.replace("sha256=", "")),
    Buffer.from(expectedSignature)
  );
}

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 and cause signature verification failures.

Supported Events

Event	Description
`deposit.created`	A new deposit has been created.
`deposit.processing`	The deposit is being processed by the provider.
`deposit.completed`	The deposit was successfully completed.
`deposit.failed`	The deposit failed.
`payout.created`	A new payout has been created.
`payout.processing`	The payout is being processed.
`payout.completed`	The payout was successfully completed.
`payout.failed`	The payout failed.
`transaction.updated`	A transaction status changed.

Handling Webhook Events

After verifying the signature:

Validate the event type.
Retrieve the transaction if necessary.
Update your internal records.
Return a successful response.

Example:

switch (event.type) {
  case "deposit.completed":
    await fulfillOrder(event.data);
    break;

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

Response Requirements

Your webhook endpoint must respond quickly. Successful response:

HTTP/1.1 200 OK

Example:

{
  "received": true
}

If your endpoint does not acknowledge the event, KryptaPay may retry the delivery.

Retry Policy

If your endpoint returns:

A timeout.
A network error.
A 5xx HTTP status code.

KryptaPay will retry webhook delivery. Your webhook handler should therefore be:

Idempotent.
Fast.
Safe to execute multiple times.

Best Practices

Always verify X-KryptaPay-Signature.
Store processed event IDs to prevent duplicates.
Return 200 OK after successful processing.
Process heavy tasks asynchronously.
Use HTTPS endpoints only.
Log webhook event IDs for debugging.
Do not expose your webhook secret.

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

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

​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

Handling Webhook Events

Response Requirements

Retry Policy

Best Practices

Next Steps