# Webhooks

## OpenAPI Specification

```yaml
openapi: 3.1.0
info:
  title: ''
  description: ''
  version: 1.0.0
paths: {}
webhooks:
  '':
    post:
      summary: Webhooks
      deprecated: false
      description: >-
        ## Overview


        Webhooks allow your application to receive real-time notifications when
        specific events occur within Vrtx. When an event is triggered, Vrtx
        sends an HTTPS `POST` request to the webhook URL registered by your
        organization for the corresponding event code.


        ## Supported Events


        | Event Code | Description |

        |---|---|

        | `onboarding.complete` | Triggered when a customer's onboarding process
        is successfully completed. |

        | `topup.complete` | Triggered when a top-up to a business account is
        successfully completed. |

        | `payout.pending` | Triggered when a payout is created and is pending
        submission to the bank. |

        | `payout.processing` | Triggered when a payout is being processed. |

        | `payout.failed` | Triggered when a payout fails. |

        | `payout.completed` | Triggered when a payout is successfully
        completed. |


        ## How Webhook Delivery Works


        1. Register a webhook URL in the business portal.

        2. When one of the events occurs, Vrtx generates a webhook event.

        3. Vrtx sends the event to the registered URL using an HTTPS `POST`
        request.

        4. The request contains a standard webhook envelope and event-specific
        information inside the `data` object.


        ## Webhook Payload


        All webhook events use the same top-level payload structure.


        Event-specific fields are returned inside the `data` object.


        ```json

        {
          "id": "3f9a1c02-8b7d-4e21-9c3a-1a2b3c4d5e6f",
          "code": "payout.completed",
          "created_at": "2026-07-06T11:20:14.220Z",
          "webhook_id": "d292e3c5-b4de-464c-b1ca-d4361e557f20",
          "data": {}
        }

        ```


        ### Payload Fields


        | Field | Type | Description |

        |---|---|---|

        | `id` | UUID | Unique identifier for the webhook event. |

        | `code` | string | Event code indicating the type of event. |

        | `created_at` | string | Timestamp indicating when the event was
        created, in ISO 8601 format. |

        | `webhook_id` | UUID | Identifier of the registered webhook receiving
        the event. |

        | `data` | object | Event-specific payload containing details about the
        affected resource. |


        ## Example


        A completed payout event is delivered with the event code:


        ```text

        payout.completed

        ```


        The `data` object contains the payout-specific information associated
        with the event.
      tags: []
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties: {}
            examples:
              '1':
                value:
                  id: dbd62ce2-d074-459f-a039-223d8f4a2778
                  code: onboarding.complete
                  created_at: '2026-09-03T14:49:24.582Z'
                  webhook_id: 78005b4b-c551-45c9-8a83-87e26ebdfe1c
                  data:
                    customer_id: fe141fcb-ebe0-410c-a4e6-5a12766db0b2
                    mobile_number: 9665XXXXXX07
                    status: active
                    completed_at: '2026-09-03T14:49:24.535Z'
                    external_reference: null
                summary: onboarding.complete
              '2':
                value: |-
                  {
                      "id": "fd05a1da-313e-4caa-a589-878ef7507ff9",
                      "code": "topup.completed",
                      "createdAt": "2026-09-03T14:41:21.850Z",
                      "webhookId": "594739b7-ad3f-41b2-a350-aab66ad30cee",
                      "data": {
                          "topupId": "fund_1003dff62905c",
                          "amount": 150,
                          "currency": "SAR",
                          "status": "PROCESSED",
                          "completedAt": "2026-09-03T14:41:21.820Z",
                          "reference": "SD5384237"
                      }
                summary: topup.completed
              '3':
                value:
                  id: 8ab1cb73-30a4-42e8-a60e-86e7661e2ba1
                  event_code: payout.pending
                  created_at: '2026-09-03T14:43:05.744Z'
                  webhook_id: 8203907f-e9f0-436b-975a-9f0bb0627eb0
                  data:
                    payout_id: payout_100d2cb338019
                    status: PENDING
                    amount: 10
                    currency: SAR
                    receiver:
                      customer_id: 220fc7f9-9daf-4ec6-836e-1d7b178a21d3
                      wallet_account_number: '211007814165'
                      mobile_number: 9665XXXXXX54
                summary: payout.pending
              '4':
                value:
                  id: 9d07e117-40f4-4159-be7f-b171fd546dad
                  event_code: payout.failed
                  created_at: '2026-09-03T14:48:14.426Z'
                  webhook_id: b0698feb-dc82-4569-8714-1c4d551265d5
                  data:
                    payout_id: payout_100d2cb338019
                    status: FAILED
                    amount: 10
                    currency: SAR
                    receiver:
                      customer_id: 220fc7f9-9daf-4ec6-836e-1d7b178a21d3
                      wallet_account_number: '211007814165'
                      mobile_number: 9665XXXXXX54
                    failure_reason: INSUFFICIENT_FUNDS
                    failed_at: '2026-09-03T14:48:14.409Z'
                summary: payout.failed
              '5':
                value:
                  id: 7d82ecc0-be2a-41fe-af30-861d6b6f55fe
                  event_code: payout.completed
                  created_at: '2026-09-03T14:48:25.275Z'
                  webhook_id: 5e3c2a5e-ac7a-4e03-93e6-3d4fef5913ed
                  data:
                    payout_id: payout_10073903abe76
                    status: COMPLETED
                    amount: 10
                    currency: SAR
                    receiver:
                      customer_id: 220fc7f9-9daf-4ec6-836e-1d7b178a21d3
                      wallet_account_number: '211007814165'
                      mobile_number: 9665XXXXXX54
                    completed_at: '2026-09-03T14:48:25.233Z'
                summary: payout.completed
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties: {}
          headers: {}
          x-apidog-name: Success
      security:
        - bearer: []
      x-apidog-folder: ''
      x-apidog-status: released
      x-run-in-apidog: https://app.apidog.com/web/project/1053095/apis/api-42629704-run
components:
  schemas: {}
  securitySchemes:
    bearerAuth:
      type: jwt
      scheme: bearer
      bearerFormat: JWT
      description: Enter your JWT access token for authentication
    bearerAuth1:
      type: jwt
      scheme: bearer
      bearerFormat: JWT
    bearerAuth2:
      type: jwt
      scheme: bearer
      bearerFormat: JWT
      description: Enter your JWT access token for authentication
    bearerAuth3:
      type: jwt
      scheme: bearer
      bearerFormat: JWT
      description: >-
        JWT issued by Keycloak. The client_id/azp in the token must map to a
        configured tenant (public, fai, neomrs; e.g., fai-sandbox -> fai) or
        requests will return 403.
    bearerAuth4:
      type: jwt
      scheme: bearer
      bearerFormat: JWT
      description: Enter your JWT access token for authentication
    bearer:
      type: http
      scheme: bearer
servers:
  - url: https://api.sandbox.vrtx.sa
    description: Sandbox
security:
  - bearer: []

```
