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

# Criar webhook

> Cria um webhook para receber notificações de eventos. O secret retornado só é exibido uma vez — guarde-o para verificar assinaturas HMAC-SHA256. Máximo de 10 webhooks por organização.



## OpenAPI

````yaml POST /api/v1/webhooks
openapi: 3.1.0
info:
  title: Integra BFI API
  version: 1.0.0
  description: >
    <img src="/public/logo_dark.webp" alt="Integra" height="36"
    style="margin-bottom:16px" />


    API pública da plataforma Integra para integrações externas.


    > [!tip]

    > **Copie a documentação completa para sua IA favorita:**

    > [Abrir página de cópia](/docs/markdown) ou baixe o [llm.txt](/llm.txt)


    ---


    ## Como começar


    ### 1. Gerar sua API Key


    Acesse o painel da Integra em **Settings > API Keys** e clique em **Nova API
    Key**.


    > [!important]

    > Copie a key gerada (`ik_live_...`) imediatamente — ela **só será exibida
    uma vez**.


    ### 2. Autenticar requests


    Envie o header `Authorization` em todas as chamadas:


    ```

    Authorization: Bearer ik_live_sua_key_aqui

    ```


    ### 3. Fazer sua primeira chamada


    ```bash

    curl -H "Authorization: Bearer ik_live_xxx" \
      https://api.useintegra.com.br/api/v1/campaigns
    ```


    > [!success]

    > Se a resposta for `200 OK` com JSON, sua integração está funcionando!


    ---


    ## Rate Limiting


    | Header | Descrição |

    |--------|-----------|

    | `X-RateLimit-Limit` | Limite total (60/min) |

    | `X-RateLimit-Remaining` | Requests restantes |

    | `X-RateLimit-Reset` | Timestamp de reset (epoch) |


    > [!warning]

    > Ao exceder **60 requests/minuto** por API Key, a API retorna status `429
    Too Many Requests`.


    ---


    ## Erros comuns


    | Status | Erro | Causa |

    |--------|------|-------|

    | `401` | Invalid API key | Key inválida ou revogada |

    | `403` | Forbidden | Key sem permissão para o recurso |

    | `429` | Rate limit exceeded | Excedeu 60 req/min |

    | `500` | Internal server error | Erro interno — contate suporte |
servers:
  - url: https://api.useintegra.com.br
    description: Production
security:
  - ApiKey: []
tags:
  - name: Campaigns
    description: Gerenciamento de campanhas de ligações
  - name: Calls
    description: Histórico de chamadas
  - name: Webhooks
    description: Gerenciamento de webhooks para notificações em tempo real
paths:
  /api/v1/webhooks:
    post:
      tags:
        - Webhooks
      summary: Criar novo webhook
      description: >-
        Cria um webhook para receber notificações de eventos. O secret retornado
        só é exibido uma vez — guarde-o para verificar assinaturas HMAC-SHA256.
        Máximo de 10 webhooks por organização.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  minLength: 1
                  maxLength: 100
                  description: Nome identificador do webhook
                url:
                  type: string
                  format: uri
                  description: URL HTTPS que receberá os eventos
                events:
                  type: array
                  items:
                    type: string
                    enum:
                      - call.completed
                      - campaign.started
                      - campaign.completed
                  minItems: 1
                  description: Eventos que o webhook deve receber
              required:
                - name
                - url
                - events
      responses:
        '201':
          description: Webhook criado. O secret só é exibido uma vez.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookCreated'
        '400':
          description: Bad Request (URL inválida, evento inválido ou limite atingido)
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                  - error
      security:
        - ApiKey: []
components:
  schemas:
    WebhookCreated:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        url:
          type: string
          format: uri
        secret:
          type: string
          description: HMAC-SHA256 secret (exibido apenas uma vez)
        events:
          type: array
          items:
            type: string
        is_active:
          type: boolean
        created_at:
          type: string
          format: date-time
      required:
        - id
        - name
        - url
        - secret
        - events
        - is_active
        - created_at
  securitySchemes:
    ApiKey:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: 'API Key da organização (Authorization: Bearer ik_live_xxx)'

````