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

# Create webhook endpoint

> Creates a signed webhook endpoint and returns the webhook signing secret once.



## OpenAPI

````yaml /openapi/payfi-v1.json post /v1/webhooks
openapi: 3.0.0
info:
  title: PayFi Partner API
  description: >-
    Partner API for PayFi compliance document automation. Dashboard Partner
    access is the admin role for exactly one partner integration; public API
    requests remain authenticated with signed partner API keys.
  version: 0.1.0
  contact: {}
servers:
  - url: https://sandbox.payfi.global
    description: Sandbox
  - url: https://api.payfi.global
    description: Production
security: []
tags:
  - name: Customers
    description: Signed partner endpoints for customer records.
  - name: Operations
    description: Signed partner endpoints for operations, documents, and upload completion.
  - name: Webhooks
    description: Partner-managed webhook endpoints and signed callback tests.
paths:
  /v1/webhooks:
    post:
      tags:
        - Webhooks
      summary: Create webhook endpoint
      description: >-
        Creates a signed webhook endpoint and returns the webhook signing secret
        once.
      operationId: WebhooksController_create
      parameters: []
      requestBody:
        required: true
        description: Webhook endpoint payload.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateWebhookEndpointRequest'
            examples:
              primary:
                value:
                  name: Acme endpoint
                  url: https://acme.example/payfi/webhooks
                  eventTypes:
                    - operation.created
                    - operation.requirements.ready
                    - operation.analysis.completed
                    - operation.action_required
      responses:
        '201':
          description: >-
            Webhook endpoint created. The secret is returned only in this
            response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookEndpointCreateResponse'
              examples:
                created:
                  value:
                    webhookId: whe_example
                    name: Acme endpoint
                    url: https://acme.example/payfi/webhooks
                    status: ACTIVE
                    eventTypes:
                      - operation.created
                      - operation.requirements.ready
                      - operation.analysis.completed
                      - operation.action_required
                    secretPreview: whsec_te...abcd
                    secret: whsec_test_returned_once
                    createdAt: '2026-05-20T12:00:00.000Z'
                    updatedAt: '2026-05-20T12:00:00.000Z'
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalidRequest:
                  value:
                    error:
                      code: INVALID_REQUEST
                      message: The request payload is invalid.
        '401':
          description: Authentication failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                unauthorized:
                  value:
                    error:
                      code: UNAUTHORIZED
                      message: Authentication failed.
      security:
        - PayFiApiKey: []
          PayFiNonce: []
          PayFiSignature: []
          PayFiIdempotencyKey: []
components:
  schemas:
    CreateWebhookEndpointRequest:
      type: object
      properties:
        name:
          type: string
          example: Acme endpoint
        url:
          type: string
          example: https://acme.example/payfi/webhooks
        eventTypes:
          type: array
          items:
            type: string
          example:
            - operation.created
            - operation.requirements.ready
            - operation.analysis.completed
      required:
        - name
        - url
    WebhookEndpointCreateResponse:
      type: object
      properties:
        webhookId:
          type: string
          example: whe_example
        name:
          type: string
          example: Acme endpoint
        url:
          type: string
          example: https://acme.example/payfi/webhooks
        status:
          type: string
          example: ACTIVE
        eventTypes:
          type: array
          items:
            type: string
          example:
            - operation.analysis.completed
        secretPreview:
          type: string
          example: whsec_te...abcd
        secret:
          type: string
          example: whsec_test_returned_once
        createdAt:
          type: string
          example: '2026-05-20T12:00:00.000Z'
        updatedAt:
          type: string
          example: '2026-05-20T12:00:00.000Z'
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              example: INVALID_SIGNATURE
            message:
              type: string
              example: The request signature is invalid.
  securitySchemes:
    PayFiApiKey:
      type: apiKey
      in: header
      name: X-PayFi-Api-Key
    PayFiNonce:
      type: apiKey
      in: header
      name: X-PayFi-Nonce
    PayFiSignature:
      type: apiKey
      in: header
      name: X-PayFi-Signature
    PayFiIdempotencyKey:
      type: apiKey
      in: header
      name: Idempotency-Key

````