> ## 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). Opcionalmente `hmac_secret` para assinatura HMAC. Limite de 10 endpoints ativos por conta.

> [!NOTE]
>
> Informe `webhook_url` e `events` (ao menos um). Opcionalmente envie
> `hmac_secret` (mínimo 16 e máximo 256 caracteres) para autenticação HMAC nas entregas.
> Cada conta pode ter no máximo 10 endpoints de webhook ativos. O secret nunca é
> devolvido na resposta.


## 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). Opcionalmente `hmac_secret` para
        assinatura HMAC. Limite de 10 endpoints ativos 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
        hmac_secret:
          type: string
          nullable: true
          minLength: 16
          maxLength: 256
          description: >-
            Secret HMAC opcional usado para assinar as entregas
            (X-UvviPay-Timestamp + X-UvviPay-Signature sobre timestamp.body).
            Nunca é devolvido nas respostas.
          example: seu-segredo-compartilhado
    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
            - failed
            - inactive
            - suspended
          description: >-
            Status operacional do endpoint. A listagem retorna `active`,
            `failed`, `inactive` e `suspended`. Novos endpoints são criados como
            `active`.
          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
        hmac_configured:
          type: boolean
          description: >-
            Indica se o endpoint possui secret HMAC cadastrado. O secret nunca é
            devolvido.
          example: true
  securitySchemes:
    client-id:
      type: apiKey
      in: header
      name: client-id
    client-secret:
      type: apiKey
      in: header
      name: client-secret

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.