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

# List webhook endpoints

> **Requires scope `webhooks`.**



## OpenAPI

````yaml /openapi.yaml get /merchant/api/webhooks
openapi: 3.1.0
info:
  title: Kori Merchant API
  version: 1.0.0
  description: >
    The Kori Merchant API lets your application collect and disburse
    mobile-money

    payments across Mali (Orange Money, Wave, Sama, Moov) and manage payouts,

    beneficiaries, bulk payments, payment links, your team, webhooks and
    settings.


    Every endpoint documented here is reachable with a **merchant API key**. You

    exchange your API key + secret for a short-lived **Bearer token** scoped to
    a set

    of permissions, then call the rest of the API with that token. The scopes
    you can

    grant are exactly the ones shown in the **API Keys** screen of your Kori
    dashboard.


    ## Authentication flow

    1. `POST /merchant/api/auth` with `X-API-Key` and `X-API-Secret` headers.
    Optionally
       request a subset of `scopes` and an expiry (`expires_in_hours`, 1–720).
    2. Use the returned `data.token` as `Authorization: Bearer <token>` on every
    other call.

    3. Each endpoint requires a specific scope; a token missing that scope gets
    `403`.


    ## Response envelope

    All responses share the shape `{ "success": boolean, "message"?: string,

    "request_id"?: string, "data"?: object }`. Errors set `success: false` and a

    human-readable `message`.


    ## Asynchronous payments

    `POST /merchant/api/pay` returns `202` with `status: "pending"` — the
    customer has

    only been *prompted*. Wait for the `payment_received` webhook (or poll the

    transaction) before treating a collection as paid. Never rely on the HTTP
    response

    alone to mark an order complete.
  contact:
    name: Kori Support
    url: https://kori.ml
servers:
  - url: https://api.kori.ml
    description: Production
  - url: https://dev.kori.ml
    description: Sandbox / development
security:
  - BearerAuth: []
tags:
  - name: Authentication
    description: Exchange your API key + secret for a scoped Bearer token.
  - name: Payments
    description: >-
      Collect from customers (`pay`), disburse (`deposit`), check balance and
      transactions.
  - name: Payouts
    description: Withdraw your balance to mobile money or bank accounts.
  - name: Beneficiaries
    description: Saved payout recipients.
  - name: Payment Links
    description: Shareable hosted payment pages.
  - name: Bulk Pay
    description: Batch disbursements to many recipients.
  - name: Team
    description: Manage dashboard team members and roles.
  - name: Webhooks
    description: Register endpoints to receive event notifications.
  - name: Settings
    description: Merchant account preferences.
paths:
  /merchant/api/webhooks:
    get:
      tags:
        - Webhooks
      summary: List webhook endpoints
      description: '**Requires scope `webhooks`.**'
      responses:
        '200':
          description: Webhooks retrieved.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Envelope'
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/Webhook'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
components:
  schemas:
    Envelope:
      type: object
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
        request_id:
          type: string
          format: uuid
    Webhook:
      type: object
      properties:
        id:
          type: integer
        url:
          type: string
          format: uri
        events:
          type: array
          items:
            $ref: '#/components/schemas/WebhookEvent'
        is_active:
          type: boolean
        failure_count:
          type: integer
        last_triggered_at:
          type: string
          format: date-time
          nullable: true
        created_at:
          type: string
          format: date-time
    WebhookEvent:
      type: string
      enum:
        - payment_received
        - payout_completed
        - payout_failed
        - bulk_pay_done
        - payment_link_used
        - team_login
        - api_key_created
        - security_alert
    Error:
      type: object
      properties:
        success:
          type: boolean
          example: false
        message:
          type: string
          example: Invalid or missing parameter
        request_id:
          type: string
          format: uuid
  responses:
    Unauthorized:
      description: Missing, invalid, or expired Bearer token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: Token lacks the required scope (or IP not whitelisted).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Scoped Bearer token from `POST /merchant/api/auth`.

````