Flutterwave

Flutterwave Webhooks API

Outbound webhook callbacks delivered by Flutterwave for charges, transfers, refunds, chargebacks, and virtual account funding. Receivers validate the `verif-hash` header against the merchant's configured secret hash before trusting the payload.

Flutterwave Webhooks API is one of 6 APIs that Flutterwave publishes on the APIs.io network, described by a machine-readable OpenAPI specification.

Tagged areas include Webhooks, Events, and Asynchronous. The published artifact set on APIs.io includes API documentation, an OpenAPI specification, and sample payloads.

GitHub OpenAPI

Documentation

📖
Documentation
https://developer.flutterwave.com/docs/webhooks.md

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/flutterwave/refs/heads/main/openapi/flutterwave-webhooks-api-openapi.yml

Examples

📝
Example
https://raw.githubusercontent.com/api-evangelist/flutterwave/refs/heads/main/examples/flutterwave-charge-completed-webhook-example.json

OpenAPI Specification

flutterwave-webhooks-api-openapi.yml Raw ↑ 
openapi: 3.1.0
info:
  title: Flutterwave Webhooks API
  description: |
    Flutterwave delivers webhook events for payments, transfers, refunds,
    chargebacks, and virtual account funding. This document describes the
    outbound HTTP callbacks Flutterwave will send to a merchant-configured
    endpoint. The receiver must respond with 2XX within 5 seconds; Flutterwave
    retries with exponential backoff.
  version: '4.0.0'
  contact:
    name: Flutterwave
    url: https://developer.flutterwave.com
    email: [email protected]
  license:
    name: Flutterwave Terms of Service
    url: https://flutterwave.com/us/terms
servers:
  - url: https://your-webhook-endpoint.example.com
    description: Merchant-hosted webhook endpoint
tags:
  - name: Webhooks
    description: Outbound webhook callbacks delivered by Flutterwave.
paths:
  /webhooks/flutterwave:
    post:
      summary: Receive Flutterwave Webhook
      description: |
        Endpoint hosted by the merchant. Flutterwave POSTs a JSON payload and
        sets the `verif-hash` header to the secret hash configured in the
        dashboard. Validate `verif-hash` before trusting the payload.
      operationId: receiveWebhook
      tags: [Webhooks]
      parameters:
        - in: header
          name: verif-hash
          required: true
          description: Pre-shared secret hash configured by the merchant.
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookEvent'
      responses:
        '200':
          description: Acknowledgement
components:
  schemas:
    WebhookEvent:
      type: object
      required: [type, data]
      properties:
        type:
          type: string
          enum:
            - charge.completed
            - charge.failed
            - transfer.completed
            - transfer.failed
            - refund.completed
            - refund.failed
            - chargeback.created
            - chargeback.updated
            - virtual_account.funded
        data:
          type: object
          properties:
            id: { type: string }
            amount: { type: number }
            currency: { type: string }
            status: { type: string }
            reference: { type: string }
            customer:
              type: object
              properties:
                id: { type: string }
                email: { type: string, format: email }
            payment_method:
              type: object
              properties:
                type: { type: string }
            processor_response:
              type: object
              properties:
                type: { type: string }
                code: { type: string }
            created_datetime: { type: string, format: date-time }
            meta: { type: object }