> ## Documentation Index
> Fetch the complete documentation index at: https://docs.krypta-pay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Learn how to configure and securely handle KryptaPay webhook notifications.

# 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](https://dashboard.krypta-pay.com/app/developers).

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.

```text theme={null}
KryptaPay
     │
     │ Transaction Event
     ▼
Webhook Endpoint
     │
     │ Verify Signature
     ▼
Your Application
     │
     │ Process Event
     ▼
Update Your Records
```

***

## Creating a Webhook Endpoint

To create a webhook endpoint:

1. Open the KryptaPay Dashboard.
2. Navigate to **Developers → Webhooks**.
3. Click **Create Endpoint**.
4. Enter your HTTPS endpoint URL.
5. Select the events you want to receive.
6. Generate or provide a webhook secret.
7. Save the endpoint.

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

<Info>
  Webhook endpoints must use HTTPS in production environments.
</Info>

***

## Webhook Request

KryptaPay sends events using HTTP POST requests.

Example:

```http theme={null}
POST https://example.com/webhooks/kryptapay
Content-Type: application/json
X-KryptaPay-Signature: sha256=8f4c7d8a2b...
```

Request body:

```json theme={null}
{
  "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:

```http theme={null}
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:

```text theme={null}
sha256=<signature>
```

***

## Verifying the Signature

Your application must verify the signature before processing the event.

### Example (Node.js)

```javascript theme={null}
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:

```javascript theme={null}
const isValid = verifyWebhookSignature(
  request.rawBody,
  request.headers["x-kryptapay-signature"],
  process.env.WEBHOOK_SECRET
);

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

<Warning>
  Always verify the signature using the raw request body. Parsing and re-serializing JSON can change the payload and cause signature verification failures.
</Warning>

***

## 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:

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

Example:

```javascript theme={null}
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 theme={null}
HTTP/1.1 200 OK
```

Example:

```json theme={null}
{
  "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

<Check>
  * 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.
</Check>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Verification and Compliance" icon="address-card" href="/compliance">
    Learn how KryptaPay uses KYB and KYC verification to provide secure, transparent, and trusted payment services.
  </Card>
</CardGroup>