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

# Register webhook

> Registers an HTTPS endpoint to receive event notifications. PCX will POST events to this URL as they occur. The organisation identity is derived from your API key. The response includes the `secret_key` used to sign every delivery — it is returned only once, so store it securely.




## OpenAPI

````yaml /api-reference/external/openapi.yaml post /public/webhooks
openapi: 3.0.3
info:
  title: PCX API
  description: >
    The PCX integration API. Every request requires two headers: `Authorization`
    (Bearer JWT for user-facing flows, or the literal string `NONE`) and
    `X-Api-Key` (your API key for server-to-server calls, or the literal string
    `NONE`). Pass `NONE` for whichever header you are not using.
  version: '1.0'
servers:
  - url: https://prod-api.pcxpay.com/v1
    description: Production
  - url: https://devs.pcxpay.com/v1
    description: Development
security: []
tags:
  - name: Payment Initiation
    description: Initiate payments and poll for status
  - name: API Keys
    description: Create and manage API keys for programmatic access
  - name: Webhooks
    description: Register endpoints and receive transaction notifications
  - name: Beneficiaries
    description: Manage payment recipients
  - name: Payments
    description: Initiate and track payments
  - name: Bank Validation
    description: Validate bank accounts before initiating a payment
  - name: Transactions
    description: Query the financial transaction ledger
  - name: Virtual Accounts
    description: Multi-currency virtual account provisioning and fund operations
  - name: Payment Links
    description: Generate shareable payment links for customer checkout
  - name: Escrow
    description: Milestone-based escrow projects, parties, contracts, and funding
paths:
  /public/webhooks:
    parameters:
      - $ref: '#/components/parameters/AuthorizationHeader'
      - $ref: '#/components/parameters/XApiKeyHeader'
    post:
      tags:
        - Webhooks
      summary: Register webhook
      description: >
        Registers an HTTPS endpoint to receive event notifications. PCX will
        POST events to this URL as they occur. The organisation identity is
        derived from your API key. The response includes the `secret_key` used
        to sign every delivery — it is returned only once, so store it securely.
      operationId: createWebhook
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateWebhookRequest'
      responses:
        '201':
          description: Webhook registered
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  parameters:
    AuthorizationHeader:
      name: Authorization
      in: header
      required: true
      description: >-
        Bearer JWT for user-facing flows (`Bearer eyJraWQ...`), or the literal
        string `NONE` when authenticating via API key.
      schema:
        type: string
        default: NONE
        example: Bearer eyJraWQ...
    XApiKeyHeader:
      name: X-Api-Key
      in: header
      required: true
      description: >-
        API key for server-to-server flows, or the literal string `NONE` when
        authenticating via JWT.
      schema:
        type: string
        default: NONE
        example: pcx_abc123_xxxx
  schemas:
    CreateWebhookRequest:
      type: object
      required:
        - endpoint_url
      properties:
        endpoint_url:
          type: string
          format: uri
          description: >
            HTTPS URL that PCX will POST events to. Must be publicly reachable
            and return a 2xx response to acknowledge receipt.
          example: https://yourapp.com/webhooks/pcx
        events:
          type: array
          items:
            type: string
          description: >
            Event types to subscribe to. Omit or send an empty array to receive
            all event types. See `GET /public/webhooks/events/catalogue` for the
            full list.
          example:
            - payment.settled
            - payment.failed
    WebhookResponse:
      allOf:
        - $ref: '#/components/schemas/StandardResponse'
        - type: object
          properties:
            data:
              $ref: '#/components/schemas/Webhook'
    StandardResponse:
      type: object
      properties:
        status:
          type: string
          enum:
            - success
            - error
          example: success
        message:
          type: string
    Webhook:
      type: object
      properties:
        webhook_id:
          type: string
        org_id:
          type: string
        endpoint_url:
          type: string
          format: uri
        secret_key:
          type: string
          description: >
            Signing secret used to compute the `X-Webhook-Signature` and
            `X-Webhook-Signature-V2` headers on every delivery. Returned only at
            registration — store it securely.
        events:
          type: array
          items:
            type: string
          description: Subscribed event types. Empty list = all events.
        status:
          type: string
          enum:
            - active
            - inactive
        created_at:
          type: string
          format: date-time
    ErrorResponse:
      type: object
      properties:
        message:
          type: string
        status:
          type: string
          enum:
            - error
  responses:
    BadRequest:
      description: Invalid request parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Missing or invalid credentials
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'

````