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

# Register webhook URLs

> Register webhook URLs to receive event notifications. URLs must be HTTPS; Blaaiz signs requests via x-blaaiz-signature. Verify deliveries with your webhook signing_secret. Your collection_url receives collection events, virtual account events, and customer KYC events such as customer.created, customer.verified, and customer.rejected. Required scope: `webhook:write`.



## OpenAPI

````yaml /api-reference/webhook/register-openapi.json post /api/external/webhook
openapi: 3.1.0
info:
  title: Blaaiz Platform API - Register Webhook URLs
  version: 1.0.0
  description: >-
    Configure webhook URLs to receive event notifications. Webhook URLs must be
    HTTPS. Blaaiz sends POST requests with event payloads and an
    x-blaaiz-signature header. Verify webhook deliveries using your webhook
    signing_secret.
servers:
  - url: https://api-prod.blaaiz.com
  - url: https://api-dev.blaaiz.com
security: []
tags:
  - name: Webhook
paths:
  /api/external/webhook:
    post:
      tags:
        - Webhook
      summary: Register webhook URLs
      description: >-
        Register webhook URLs to receive event notifications. URLs must be
        HTTPS; Blaaiz signs requests via x-blaaiz-signature. Verify deliveries
        with your webhook signing_secret. Your collection_url receives
        collection events, virtual account events, and customer KYC events such
        as customer.created, customer.verified, and customer.rejected. Required
        scope: `webhook:write`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookRegisterRequest'
            example:
              payout_url: https://yourapp.com/webhooks/payout
              collection_url: https://yourapp.com/webhooks/collection
      responses:
        '200':
          description: Webhook URLs registered successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookRegisterResponse'
              example:
                message: Webhook record created successfully
                data:
                  signing_secret: a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                status: false
                message: Invalid webhook URL format
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                status: false
                message: Invalid or missing access token
      security:
        - oauth2ClientCredentials:
            - webhook:write
components:
  schemas:
    WebhookRegisterRequest:
      type: object
      properties:
        payout_url:
          type: string
          format: uri
          description: URL to receive payout event notifications
        collection_url:
          type: string
          format: uri
          description: >-
            URL to receive collection, virtual account, and customer KYC event
            notifications. This includes customer.created, customer.verified,
            and customer.rejected.
      required:
        - payout_url
        - collection_url
    WebhookRegisterResponse:
      type: object
      properties:
        message:
          type: string
        data:
          type: object
          properties:
            signing_secret:
              type: string
              description: >-
                Your webhook signing secret. Store this securely — it is only
                returned on creation. Use it to verify x-blaaiz-signature
                headers on incoming webhooks.
          required:
            - signing_secret
      required:
        - message
        - data
    Error:
      type: object
      properties:
        status:
          type: boolean
        message:
          type: string
      required:
        - status
        - message
  securitySchemes:
    oauth2ClientCredentials:
      type: oauth2
      description: >-
        Use your OAuth client credentials to obtain a short-lived Bearer token
        from POST /oauth/token.
      flows:
        clientCredentials:
          tokenUrl: /oauth/token
          scopes:
            webhook:write: Create and update webhooks.

````