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

# Criar webhook

> Cria um endpoint de webhook para o merchant autenticado. Informe `webhook_url` e `events` (ao menos um). Limite de 3 endpoints por conta.

<Note>
  Informe `webhook_url` e `events` (ao menos um). Cada conta pode ter no máximo
  3 endpoints de webhook.
</Note>


## OpenAPI

````yaml POST /v1/webhooks
openapi: 3.0.0
info:
  title: UvviPay Public API
  description: >-
    Endpoints públicos da plataforma UvviPay para integração de subcontas
    (submerchants).
  version: 1.0.0
  contact: {}
servers:
  - url: https://api.uvvipay.com.br
    description: Produção
  - url: https://api-staging.uvvipay.com.br
    description: Staging
security:
  - client-id: []
    client-secret: []
tags: []
paths:
  /v1/webhooks:
    post:
      tags:
        - Webhooks
      summary: Criar webhook
      description: >-
        Cria um endpoint de webhook para o merchant autenticado. Informe
        `webhook_url` e `events` (ao menos um). Limite de 3 endpoints por conta.
      operationId: createWebhook
      parameters:
        - name: client-id
          in: header
          description: ID público da credencial do merchant
          required: true
          schema:
            type: string
        - name: client-secret
          in: header
          description: Secret da credencial do merchant
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateWebhookRequestDto'
      responses:
        '201':
          description: Webhook criado com sucesso
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookMutationResponseDto'
        '400':
          description: URL inválida ou limite de endpoints atingido
        '401':
          description: Credenciais inválidas ou ausentes
components:
  schemas:
    CreateWebhookRequestDto:
      type: object
      required:
        - webhook_url
        - events
      properties:
        webhook_url:
          type: string
          format: uri
          pattern: ^https://.+
          description: URL HTTPS que receberá as notificações via POST
          example: https://minhaloja.com.br/webhooks/uvvipay
        events:
          type: array
          minItems: 1
          uniqueItems: true
          description: Eventos em que o endpoint será inscrito
          items:
            type: string
            enum:
              - transaction.status.updated
              - transaction.waiting_payment
              - transaction.paid
              - transaction.refused
              - transaction.refunded
              - transaction.chargedback
              - transaction.cancelled
              - transaction.expired
              - transaction.in_analysis
              - submerchant.status.updated
              - subscription.created
              - subscription.trial_started
              - subscription.activated
              - subscription.past_due
              - subscription.cancelled
              - subscription.reactivated
              - subscription.completed
              - subscription.renewed
          example:
            - transaction.status.updated
    WebhookMutationResponseDto:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/WebhookEndpointDto'
    WebhookEndpointDto:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Identificador do endpoint, usado na atualização
        endpoint:
          type: string
          format: uri
          example: https://minhaloja.com.br/webhooks/uvvipay
        status:
          type: string
          enum:
            - active
          description: >-
            Status operacional do endpoint. Nesta API, endpoints são criados
            como active e apenas registros active aparecem na listagem.
          example: active
        created_at:
          type: string
          format: date-time
        events:
          type: array
          description: Eventos enabled neste endpoint
          items:
            type: string
            enum:
              - transaction.status.updated
              - transaction.waiting_payment
              - transaction.paid
              - transaction.refused
              - transaction.refunded
              - transaction.chargedback
              - transaction.cancelled
              - transaction.expired
              - transaction.in_analysis
              - submerchant.status.updated
              - subscription.created
              - subscription.trial_started
              - subscription.activated
              - subscription.past_due
              - subscription.cancelled
              - subscription.reactivated
              - subscription.completed
              - subscription.renewed
          example:
            - transaction.status.updated
  securitySchemes:
    client-id:
      type: apiKey
      in: header
      name: client-id
    client-secret:
      type: apiKey
      in: header
      name: client-secret

````