> ## Documentation Index > Fetch the complete documentation index at: https://docs.pay.v4companyamaral.com/llms.txt > Use this file to discover all available pages before exploring further. # Cadastrar webhook do lojista > Endpoint que recebe eventos da V4 Pay (ex.: charge.paid) com assinatura HMAC-SHA256 do corpo no header X-V4Pay-Signature. ## OpenAPI ````yaml /openapi.yaml post /webhook-endpoints openapi: 3.1.0 info: title: V4Pay API version: 2.0.0 description: > API do gateway de pagamentos V4Pay: autenticação, clientes, cobranças, cupons e emissão de Pix — cada lojista tem uma conta de recebimento no CNPJ dele, e a cobrança leva um split com a taxa do V4 Pay. Todas as rotas protegidas usam token JWT — o usuário é identificado pelo token, nunca por `user_id` no corpo da requisição. servers: - url: https://v4pay-api.vercel.app description: Produção. - url: http://localhost:3000 description: Ambiente local de desenvolvimento. security: [] tags: - name: Pix description: Emitir e consultar cobranças Pix — o coração da API. - name: Cobranças description: Registro direto de cobranças e a listagem do histórico da loja. - name: Clientes description: Cadastro de pagadores para reutilizar nas cobranças. - name: Links de pagamento description: URLs públicas reutilizáveis que abrem o checkout com o valor definido. - name: Checkout (público) description: >- As rotas que a página de pagamento usa — sem autenticação, o pagador não tem conta. - name: Produtos description: Catálogo da loja; um produto pode virar cobrança ou link. - name: Cupons description: Descontos aplicados no checkout e na emissão por produto. - name: Assinaturas description: Cobrança recorrente, gerada por um cron diário. - name: Webhooks (endpoints) description: >- As URLs do seu servidor que recebem os eventos da loja, com assinatura HMAC. - name: Chaves de API description: Credenciais de integração (v4pay_test_ / v4pay_live_), revogáveis. - name: Conta de recebimento description: Cadastro da empresa e a conta que recebe — vale no modo subconta. - name: Aprovação de produção description: >- O fluxo para liberar a operação em produção — dados da empresa, documentos e análise da equipe. - name: Saques description: >- Pedidos de saque do saldo — suspensos no modo conta única (REPASSE_MANUAL). - name: Membros da loja description: Convites e papéis de quem opera a loja junto com o dono. - name: Conta (auth) description: Cadastro, login, perfil e a troca de ambiente da sessão. - name: Auditoria description: Trilha das ações feitas na loja, com quem fez e de onde. - name: Sistema description: Saúde da API. - name: Interno description: >- USO INTERNO DO PAINEL — documentado por transparência, não para integração: pode mudar sem aviso (Roadmap, aprovações da equipe, cron, login com Google, onboarding). paths: /webhook-endpoints: post: tags: - Webhooks (endpoints) summary: Cadastrar webhook do lojista description: >- Endpoint que recebe eventos da V4 Pay (ex.: charge.paid) com assinatura HMAC-SHA256 do corpo no header X-V4Pay-Signature. requestBody: required: true content: application/json: schema: type: object required: - url properties: url: type: string example: https://meusite.com/webhooks/v4pay name: type: string description: Nome para identificar na lista events: type: array items: type: string enum: - charge.created - charge.paid - subscription.charged - withdrawal.completed - withdrawal.rejected description: Eventos a receber. Omitido ou vazio = todos. secret: type: string pattern: ^whsec_[0-9a-f]{32}$ description: >- Opcional — segredo de assinatura gerado do SEU lado (ex.: no navegador, para o lojista ver antes de salvar). Só no formato exato `whsec_` + 32 hexadecimais minúsculos; fora disso, ou com os 32 caracteres iguais, `400`. IMPORTANTE: a API confere o FORMATO, não a aleatoriedade — este valor assina o `X-V4Pay-Signature` dos seus eventos, então gere-o com um gerador criptográfico (`crypto.getRandomValues`/`randomBytes`), nunca um valor fixo ou derivado de senha: secret previsível é evento forjável. Omitido, a API gera (com entropia garantida). responses: '201': description: Endpoint cadastrado (o secret vem na resposta). content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/WebhookEndpoint' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' security: - bearerAuth: [] components: schemas: WebhookEndpoint: type: object description: Endpoint do lojista que recebe eventos da V4 Pay. properties: id: type: string format: uuid name: type: - string - 'null' description: Nome dado pelo lojista, só para identificar na lista. example: Loja principal events: type: array items: type: string enum: - charge.created - charge.paid - subscription.charged - withdrawal.completed - withdrawal.rejected description: Eventos que o endpoint assina. Lista vazia = recebe todos. version: type: string example: v1 description: Versão do formato do evento entregue. url: type: string example: https://meusite.com/webhooks/v4pay secret: type: string description: Usado para validar a assinatura HMAC (X-V4Pay-Signature). example: whsec_a1b2c3d4... active: type: boolean created_at: type: string format: date-time updated_at: type: string format: date-time Error: type: object properties: error: type: object properties: message: type: string description: Descrição da mensagem de erro. ErrorAuth: type: object description: > Segundo formato de erro, usado só pelo middleware de autenticação (token ausente, inválido ou chave revogada). Repare que aqui `error` é uma string, não um objeto. properties: error: type: string example: Token JWT ou chave de API ausente responses: BadRequest: description: Erro de validação nos dados enviados. content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: Não autenticado. Repare no formato — `error` é string neste caso. content: application/json: schema: $ref: '#/components/schemas/ErrorAuth' securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: > Token JWT obtido em `/auth/login`, enviado no cabeçalho `Authorization` no formato `Bearer `. ````