Webhook Setup

Overview

Webhooks are an important part of your payment integration. They allow Flutterwave notify you about events that happen on your account, such as a successful payment or a failed transaction.

A webhook URL is an endpoint on your server where you can receive notifications about such events. When an event occurs, we'll make a POST request to that endpoint, with a JSON body containing the details about the event, including the type of event and the data associated with it.

When to use webhooks

Webhooks are supported for all kinds of payment methods, but they're especially useful for methods and events that happen outside your application's control, such as:

1. getting paid via mobile money or USSD
2. a customer being charged for their subscription (recurring payments)
3. a pending payment transitions to successful These are all asynchronous actions—they are not controlled by your application, so you won't know when they are completed, unless we notify you or you check later.

Setting up a webhook allows us to notify you when these payments are completed. Within your webhook endpoint, you can then:

Update a customer's membership records in your database when a subscription payment succeeds. Email a customer when a subscription payment fails. Update your order records when the status of a pending payment is updated to successful.

How to handle Charge Event notifications we send via webhook.

First you need to make sure the php file is accessible publicly. Copy the address to your publicly accessible webhook url and configure the webhook settings on your flutterwave dashboard. Use the Webhook::listen() methods. make sure you pass in your secret_hash as the parameter.

require __DIR__.'/vendor/autoload.php';

use Flutterwave\Exception\WebhookException;
use Flutterwave\Library\Event;
use Flutterwave\Library\EventType;
use Flutterwave\Library\Webhook;

try{
    $wbhk = Webhook::listen("YOUR_SECRET_HASH");
} catch ( WebhookException $e) {
    echo json_encode(
        [
        'status'  => 'error',
        'message' => $e->getMessage()
        ]
    );
}

Handle Specific Hook

You can handle specific hook using the ::on method. Here is a sample that show how to handle a completed charge payment hooks.

$wbhk::on(
    Event::CHARGE_COMPLETED, function (array $data) {
        //re verify transaction
        // give value
        //update db.
    }
);

Handle Subscription cancellation hook.

$wbhk::on(
    Event::SUBSCRIPTION_CANCELLED, function (array $data) {
        //re verify transaction
        // give value
        //update db.
    }
);

Handle a completed Transfer Hook.

$wbhk::on(
    Event::TRANSFER_COMPLETED, function (array $data) {
        //re verify transaction
        // give value
        //update db.
    }
);

Handle BVN Verification Hook

$wbhk::on(
    Event::BVN_COMPLETED, function (array $data) {
        //re verify transaction
        // give value
        //update db.
    }
);

Handle Virtual Card Debit Hook

$wbhk::on(
    EventType::VIRTUAL_CARD_DEBIT, function (array $data) {
        //re verify transaction
        // give value
        //update db.
    }
);

Handle Virtual Card OTP hook

$wbhk::on(
    EventType::VIRTUAL_CARD_OTP, function (array $data) {
        dd($data);
    }
);