> ## Documentation Index > Fetch the complete documentation index at: https://documentacao.credicarro.com.br/llms.txt > Use this file to discover all available pages before exploring further. # Cadastrar webhook > Cadastra um webhook ativo para o parceiro autenticado. É permitido mais de um webhook por tipo. A resposta traz o segredo de assinatura (`segredo_assinatura`) em claro, usado para validar o header `X-CrediCarro-Signature` das notificações. Ele não pode ser recuperado depois, então guarde-o nesse momento. Cadastra uma configuração de webhook para o parceiro identificado automaticamente pelo token de acesso. > [!WARNING] > > A `url` precisa ser **HTTPS** e pública, com até 2048 caracteres: sem `localhost`, IP privado, usuário/senha ou `#fragmento`. Caso contrário, a API retorna `422` com `Organization.Webhook.InvalidEndpoint`. Uma URL malformada (não absoluta) retorna `400` com `Validation.Url.Invalid`. ## Tipos de webhook | Valor | Tipo | Disponibilidade | | - | - | - | | `1` | **Cliente** | ⚪ **Sem envio no momento** — pode ser cadastrado, mas não envia notificações. | | `2` | **Simulação** | ⚪ **Sem envio no momento** — pode ser cadastrado, mas não envia notificações. | | `3` | **Proposta** | 🟢 **Disponível** — envia uma notificação a cada atualização da proposta. | > [!WARNING] > > Os tipos Cliente (`1`) e Simulação (`2`) podem ser configurados, mas não enviam notificações. Atualmente, apenas o tipo Proposta (`3`) está disponível. ## Tipos de autenticação | Valor | Significado | | - | - | | `1` | **Nenhuma** — a requisição é enviada sem credencial de autenticação. | | `2` | **Basic** — envia `Authorization: Basic {credencial}`, com `credencial` em Base64 de `usuario:senha`. | | `3` | **JWT** — envia `Authorization: Bearer {credencial}`. | > [!NOTE] > > A credencial é obrigatória para Basic e JWT, com até 2048 caracteres. Com `tipo_autenticacao` = 1, ela é ignorada. O tipo de autenticação e a credencial não podem ser alterados depois do cadastro. É permitido mais de um webhook por tipo. ## Segredo de assinatura A resposta traz `segredo_assinatura`, usado para verificar a autenticidade das notificações recebidas. Ele é exibido **apenas nesta resposta** — guarde-o com segurança, pois não é possível consultá-lo novamente. Consulte [Verificação e segurança](https://documentacao.credicarro.com.br/pages/webhooks/security.md). ## OpenAPI ````yaml POST /v1/webhook openapi: 3.1.0 info: title: API Credicarro description: API para gerenciamento de cobranças e pagamentos usando o Credicarro. version: 1.0.0 servers: - url: https://api.staging.credicarro.com.br/integration description: Servidor para o ambiente de staging - url: https://api.credicarro.com.br/integration description: Servidor para o ambiente de produção security: [] paths: /v1/webhook: post: tags: - Webhook summary: Cadastrar um webhook description: > Cadastra um webhook ativo para o parceiro autenticado. É permitido mais de um webhook por tipo. A resposta traz o segredo de assinatura (`segredo_assinatura`) em claro, usado para validar o header `X-CrediCarro-Signature` das notificações. Ele não pode ser recuperado depois, então guarde-o nesse momento. requestBody: required: true content: application/json: schema: type: object required: - tipo - url - tipo_autenticacao additionalProperties: false properties: tipo: type: integer format: int32 description: | Evento notificado pelo webhook. Valores aceitos: - 1 = Customer - 2 = Simulation - 3 = Proposal example: 3 url: type: string description: >- URL HTTPS pública, com até 2048 caracteres, que receberá as notificações (sem localhost, IP privado, usuário/senha ou fragmento). example: https://parceiro.com.br/webhooks/credicarro tipo_autenticacao: type: integer format: int32 description: > Autenticação enviada pela Credicarro ao chamar a URL. Não pode ser alterada depois da criação. Valores aceitos: - 1 = None (sem autenticação) - 2 = Basic - 3 = Jwt example: 2 credencial: type: string description: > Credencial enviada no header `Authorization`. Obrigatória para Basic (valor em Base64 de `usuario:senha`, enviado como `Basic {credencial}`) e Jwt (token enviado como `Bearer {credencial}`). example: dXN1YXJpbzpzZW5oYQ== responses: '201': description: Webhook cadastrado com sucesso content: application/json: schema: type: object properties: id_webhook: type: string format: uuid description: Identificador único do webhook example: 3fa85f64-5717-4562-b3fc-2c963f66afa6 segredo_assinatura: type: string description: >- Segredo usado para validar a assinatura `X-CrediCarro-Signature`. Retornado somente nesta resposta. example: '400': description: >- Erro na requisição (por exemplo, `Validation.Url.Invalid` para URL malformada, `Validation.Field.Required` para `credencial` ausente em Basic ou Jwt) content: application/json: schema: $ref: '#/components/schemas/ProblemDetails' '403': $ref: '#/components/responses/IntegrationInactive' '422': description: >- URL não aceita (`Organization.Webhook.InvalidEndpoint`: precisa ser HTTPS pública, sem localhost, IP privado, usuário/senha ou fragmento) ou integração inativa (`Organization.Webhook.ActivationIntegrationInactive`) content: application/json: schema: $ref: '#/components/schemas/ProblemDetails' '503': description: >- Não foi possível proteger a credencial agora (`Organization.Webhook.CredentialProtectionUnavailable`). Tente de novo. content: application/json: schema: $ref: '#/components/schemas/ProblemDetails' security: - bearerAuth: [] components: schemas: ProblemDetails: type: object properties: tipo: type: string description: Tipo de problema encontrado example: Validation.Cpf.Invalid titulo: type: string description: Título do erro example: Requisição inválida status: type: integer format: int32 description: Status Code do erro example: 400 detalhe: type: string description: Descrição do erro example: O CPF informado em 'cpf' é inválido. campo: type: string nullable: true description: Campo da requisição relacionado ao erro, quando houver example: cpf erros: type: array description: >- Lista de erros. Presente só quando o JSON enviado está malformado ou tem um valor de tipo errado. items: type: object properties: codigo: type: string description: Código estável do erro example: Validation.InvalidFormat mensagem: type: string description: Mensagem em português example: O valor informado para 'valorVeiculo' não é um número válido. campo: type: string nullable: true description: Campo inválido, quando houver example: cpf additionalProperties: false responses: IntegrationInactive: description: >- Integração do parceiro inativa ou não encontrada (`Integration.Access.Inactive`, `Integration.Access.OrganizationNotFound`) content: application/json: schema: $ref: '#/components/schemas/ProblemDetails' securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- Cabeçalho de autenticação Bearer no formato `Bearer ` onde `` é seu TOKEN de autenticação ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.