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

# Configurar webhook da conta

> **Requer token Bearer no header Authorization**.

Configura ou atualiza a URL de webhook para um tipo de evento específico. Se já existir um webhook configurado para o mesmo tipo de evento, ele será atualizado (comportamento de upsert).

**Eventos disponíveis:**
- `cash_in` - PIX recebido
- `cash_out` - PIX enviado
- `refund_in` - Estorno de recebimento (devolução solicitada)
- `refund_out` - Devolução recebida

**Headers personalizados:**
Você pode configurar até 5 headers customizados para autenticação do seu endpoint.
Headers bloqueados (não permitidos): host, content-length, connection, transfer-encoding, content-type, user-agent.

**Invalidação de cache:**
Ao configurar um webhook, o cache é invalidado automaticamente no serviço de notificações. Transações subsequentes usarão a nova configuração imediatamente.



## OpenAPI

````yaml post /api/webhooks
openapi: 3.0.0
info:
  title: Fire Banking Public API
  description: >-
    API Pública da Plataforma Fire Banking para integração com serviços de
    pagamento PIX e gestão de contas
  version: 0.1.0
  contact: {}
servers:
  - url: https://api.public.firebanking.com.br
    description: Servidor de produção
security: []
tags:
  - name: auth
    description: Endpoints de autenticação
  - name: Balance
    description: Endpoints de consulta de saldo
  - name: PIX
    description: Endpoints de transações PIX
  - name: Webhooks
    description: Endpoints de gerenciamento de webhooks
paths:
  /api/webhooks:
    post:
      tags:
        - Webhooks
      summary: Configurar webhook da conta
      description: >-
        **Requer token Bearer no header Authorization**.


        Configura ou atualiza a URL de webhook para um tipo de evento
        específico. Se já existir um webhook configurado para o mesmo tipo de
        evento, ele será atualizado (comportamento de upsert).


        **Eventos disponíveis:**

        - `cash_in` - PIX recebido

        - `cash_out` - PIX enviado

        - `refund_in` - Estorno de recebimento (devolução solicitada)

        - `refund_out` - Devolução recebida


        **Headers personalizados:**

        Você pode configurar até 5 headers customizados para autenticação do seu
        endpoint.

        Headers bloqueados (não permitidos): host, content-length, connection,
        transfer-encoding, content-type, user-agent.


        **Invalidação de cache:**

        Ao configurar um webhook, o cache é invalidado automaticamente no
        serviço de notificações. Transações subsequentes usarão a nova
        configuração imediatamente.
      operationId: WebhooksConfigController_setupWebhook
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetupWebhookInputDto'
      responses:
        '200':
          description: Webhook configurado com sucesso
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SetupWebhookOutputDto'
        '400':
          description: Dados inválidos (URL não é HTTPS, tipo de evento inválido, etc.)
        '401':
          description: Token não fornecido ou inválido
        '404':
          description: Conta não encontrada
        '500':
          description: Erro interno ao configurar webhook
      security:
        - bearer: []
components:
  schemas:
    SetupWebhookInputDto:
      type: object
      required:
        - url
        - eventType
      properties:
        url:
          type: string
          format: uri
          description: >-
            URL HTTPS do endpoint que receberá os webhooks. Deve usar protocolo
            HTTPS.
          example: https://api.example.com/webhooks/pix
        eventType:
          type: string
          description: Tipo de evento para receber notificações
          enum:
            - cash_in
            - cash_out
            - refund_in
            - refund_out
          example: cash_in
        headers:
          type: array
          description: >-
            Headers customizados para autenticação (máximo 5). Headers
            bloqueados: host, content-length, connection, transfer-encoding,
            content-type, user-agent
          maxItems: 5
          items:
            $ref: '#/components/schemas/WebhookHeaderDto'
          example:
            - key: Authorization
              value: Bearer token123
            - key: X-Webhook-Secret
              value: abc123
    SetupWebhookOutputDto:
      type: object
      required:
        - success
        - message
      properties:
        success:
          type: boolean
          description: Indica se a operação foi bem-sucedida
          example: true
        message:
          type: string
          description: Mensagem descritiva do resultado
          example: Webhook configurado com sucesso
    WebhookHeaderDto:
      type: object
      required:
        - key
        - value
      properties:
        key:
          type: string
          description: Nome do header customizado
          example: Authorization
        value:
          type: string
          description: Valor do header
          example: Bearer token123
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Enter JWT token

````