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

# Introduction

> Learn how to integrate and handle Mavapay webhooks

# Webhook Integration Guide

Webhooks allow your application to receive real-time notifications about events that occur in your Mavapay account. This guide explains how to integrate, secure, and handle webhook notifications.

## Overview

Mavapay uses webhooks to notify your application when events happen in your account. Instead of polling our API, webhooks enable your application to be notified in real-time when events occur.

## Setting Up Webhooks

### 1. Register Your Webhook Endpoint

First, [register your webhook](/api-reference/endpoint/webhook/register-webhook) endpoint using our API:

```javascript theme={null}
const response = await fetch('https://api.mavapay.co/api/v1/webhook/register', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'your_api_key_here'
  },
  body: JSON.stringify({
    url: 'https://your-domain.com/webhook',
    secret: 'your_webhook_secret'
  })
});
```

### 2. Update Webhook Configuration

You can update your webhook configuration at any time:

```javascript theme={null}
const response = await fetch('https://api.mavapay.co/api/v1/webhook', {
  method: 'PUT',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'your_api_key_here'
  },
  body: JSON.stringify({
    url: 'https://your-new-domain.com/webhook',
    secret: 'your_new_webhook_secret'
  })
});
```

## Event Types

Mavapay currently supports two types of webhook events:

1. `payment.received` - Triggered when a payment is received
2. `payment.sent` - Triggered when a payment is sent

### Event Payloads

#### payment.received

```json theme={null}
{
  "event": "payment.received",
  "data": {
    "id": "tx_123456789",
    "amount": 500000,
    "currency": "NGN",
    "status": "SUCCESS",
    "metadata": {
      "hash": "189727ef2e0f35921af7858b96e27cbad960b0ec2bb2a4ab73b6a231f9ce8727",
      "reference": "MP123456789",
      ...
    }
  }
}
```

#### payment.sent

```json theme={null}
{
  "event": "payment.sent",
  "data": {
    "id": "tx_123456789",
    "amount": 500000,
    "currency": "NGN",
    "status": "SUCCESS",
    "metadata": {
      "bankAccountNumber": "0149203789",
      "bankAccountName": "John Doe",
      "bankName": "GTBANK PLC",
      "reference": "MP123456789",
      ...
    }
  }
}
```

## Security

### Verifying Webhook Signatures

To ensure the webhook requests are coming from Mavapay, we sign each request with your webhook secret. The signature is included in the `X-Mavapay-Signature` header.

Here's how to verify the signature (Node.js example):

```javascript theme={null}
const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

// In your webhook handler
app.post('/webhook', (req, res) => {
  const signature = req.headers['x-mavapay-signature'];
  const isValid = verifyWebhookSignature(
    req.body,
    signature,
    'your_webhook_secret'
  );

  if (!isValid) {
    return res.status(400).json({ error: 'Invalid signature' });
  }

  // Process the webhook
  const { event, data } = req.body;
  // Handle the event...

  res.json({ received: true });
});
```

## Best Practices

1. **Verify Signatures**: Always verify webhook signatures to ensure requests are from Mavapay.

2. **Idempotency**: Process webhooks idempotently using the event ID to avoid duplicate processing.

3. **Quick Response**: Respond to webhooks quickly (within 5 seconds) to acknowledge receipt.

4. **Retry Logic**: Implement retry logic in case your endpoint is temporarily unavailable.

5. **Logging**: Log webhook requests for debugging and auditing purposes.

6. **Error Handling**: Implement proper error handling for failed webhook processing.

## Testing Webhooks

You can use our staging environment to test webhooks:

```bash theme={null}
https://staging.api.mavapay.co/api/v1
```

We recommend using tools like [webhook.site](https://webhook.site) or [ngrok](https://ngrok.com) for local development.

### Test Event

You can trigger a test event to verify your webhook setup:

```javascript theme={null}
const response = await fetch('https://api.mavapay.co/api/v1/webhook/test', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'your_api_key_here'
  }
});
```

## Troubleshooting

Common issues and solutions:

1. **Invalid Signature**: Double-check your webhook secret and signature verification code.

2. **Timeout**: Ensure your endpoint responds within 5 seconds.

3. **SSL Error**: Make sure your endpoint has a valid SSL certificate.

4. **Wrong Content-Type**: Your endpoint should accept `application/json`.

## Support

If you need help with webhooks:

* Email: [info@mavapay.co](mailto:info@mavapay.co)
* Documentation: [https://docs.mavapay.co](https://docs.mavapay.co)
* API Reference: [https://docs.mavapay.co/api-reference](https://docs.mavapay.co/api-reference)