---
title: "Webhooks"
description: "Learn how to receive real-time updates for your transactions."
---

Webhooks allow your application to receive real-time notifications when a transaction's status changes. Instead of polling our API, we'll send a POST request to your server.

## Setting Up

There are two ways to configure your webhook destination:

1.  **Global Webhook URL**: Set a default URL in your [Business Dashboard](https://criptpay.vercel.app). This will be used for all transactions.
2.  **Per-Transaction Callback**: Provide a `callbackUrl` in the `initiate` request body. This takes precedence over the global URL.

### The Callback URL

Your external callback URL for the Criptpay backend is:
`https://criptpay-f2lv.onrender.com/api/webhook`

## Webhook Payload

When a status change occurs, we send a POST request with a JSON body.

### Example Payload

```json
{
  "event": "transfer.updated",
  "data": {
    "transactionId": "65b...",
    "reference": "SW-12345",
    "status": "COMPLETED",
    "amount": 100,
    "currency": "NGN",
    "timestamp": "2024-01-31T12:00:00.000Z"
  }
}
```

### Event Types

| Event              | Description                                                                                  |
| :----------------- | :------------------------------------------------------------------------------------------- |
| `transfer.updated` | Sent whenever the transaction status changes (e.g., from `AWAITING_DEPOSIT` to `COMPLETED`). |

## Implementation Tips

- **Acknowledge Quickly**: Return a `200 OK` response immediately to acknowledge receipt.
- **Idempotency**: Use the `reference` or `transactionId` to ensure you don't process the same update twice.
- **Timeout**: Our system waits up to 5 seconds for your server to respond.