---
title: "Criar Webhook"
method: POST
path: "/v1/webhooks"
tags: ["Webhooks"]
---

# Criar Webhook

`POST /v1/webhooks`

Cria um webhook para receber notificações de eventos do sistema via HTTP.

## Headers

- `User-Agent` string
- `X-Idempotency-Key` string

## Request body

- WebhookObject
  - `id` integer — ID do webhook
  - `name` string, nullable — Nome de identificação do webhook
  - `url` string, required — Endereço onde as requisições serão realizadas
  - `content_type` string, nullable — Content-type da requisição que será realizada. Valores válidos `application/json` (valor padrão) ou `application/x-www-form-urlencoded`.
  - `events` string[], required — Eventos que devem gerar notificações para o webhook. Escolha um ou mais eventos.
  - `active` boolean, nullable — Define se o webhook estará ativo, recebendo notificações. O valor padrão é `true`.
  - `ssl_verification_enabled` boolean, nullable — Define se a verificação SSL está habilitada no webhook.
  - `subaccounts` boolean — Define se o webhook estará ativo para os eventos das subcontas.
  - `bank_billet_account_id` integer, nullable — ID da [Carteira de Cobrança](/reference/post_v1-bank-billet-accounts). Se informado, o webhook apenas receberá notificações de eventos relacionados à carteira indicada.
  - `auth_kind` 'none' | 'basic_auth' | 'bearer' | 'api_key', nullable — Tipo de autenticação configurado. Retornado nas respostas. Para configurar, envie o objeto `auth` no body.
  - `auth` object, nullable — Configuração de autenticação do endpoint receptor. Apenas para criação/atualização — não retornado nas respostas.
    - `kind` 'none' | 'basic_auth' | 'bearer' | 'api_key' — Tipo de autenticação: `none`, `basic_auth`, `bearer` ou `api_key`.
    - `username` string, nullable — Usuário (somente `basic_auth`).
    - `password` string, nullable — Senha (somente `basic_auth`). Deixe em branco para manter a senha atual.
    - `token` string, nullable — Token (somente `bearer`). Deixe em branco para manter o token atual.
    - `header_name` string, nullable — Nome do header (somente `api_key`). Ex: `X-API-Key`.
    - `header_value` string, nullable — Valor do header (somente `api_key`). Deixe em branco para manter o valor atual.
  - `created_at` string, date-time, nullable — Data e hora de criação do registro
  - `updated_at` string, date-time, nullable — Data e hora da última atualização do registro

## Response `201`

Webhook criado com Basic Auth

- WebhookObject
  - `id` integer — ID do webhook
  - `name` string, nullable — Nome de identificação do webhook
  - `url` string, required — Endereço onde as requisições serão realizadas
  - `content_type` string, nullable — Content-type da requisição que será realizada. Valores válidos `application/json` (valor padrão) ou `application/x-www-form-urlencoded`.
  - `events` string[], required — Eventos que devem gerar notificações para o webhook. Escolha um ou mais eventos.
  - `active` boolean, nullable — Define se o webhook estará ativo, recebendo notificações. O valor padrão é `true`.
  - `ssl_verification_enabled` boolean, nullable — Define se a verificação SSL está habilitada no webhook.
  - `subaccounts` boolean — Define se o webhook estará ativo para os eventos das subcontas.
  - `bank_billet_account_id` integer, nullable — ID da [Carteira de Cobrança](/reference/post_v1-bank-billet-accounts). Se informado, o webhook apenas receberá notificações de eventos relacionados à carteira indicada.
  - `auth_kind` 'none' | 'basic_auth' | 'bearer' | 'api_key', nullable — Tipo de autenticação configurado. Retornado nas respostas. Para configurar, envie o objeto `auth` no body.
  - `auth` object, nullable — Configuração de autenticação do endpoint receptor. Apenas para criação/atualização — não retornado nas respostas.
    - `kind` 'none' | 'basic_auth' | 'bearer' | 'api_key' — Tipo de autenticação: `none`, `basic_auth`, `bearer` ou `api_key`.
    - `username` string, nullable — Usuário (somente `basic_auth`).
    - `password` string, nullable — Senha (somente `basic_auth`). Deixe em branco para manter a senha atual.
    - `token` string, nullable — Token (somente `bearer`). Deixe em branco para manter o token atual.
    - `header_name` string, nullable — Nome do header (somente `api_key`). Ex: `X-API-Key`.
    - `header_value` string, nullable — Valor do header (somente `api_key`). Deixe em branco para manter o valor atual.
  - `created_at` string, date-time, nullable — Data e hora de criação do registro
  - `updated_at` string, date-time, nullable — Data e hora da última atualização do registro

## Other responses

- `401` — Falha de autenticação. Token inválido
- `403` — Falha de permissão. Você não tem o Scope obrigatório para essa chamada.
- `422` — Webhook inválido

---

[API](https://skmtc.net/kobana/apis/cobran-as.md) · [All operations](https://skmtc.net/kobana/apis/cobran-as/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/kobana/cobran-as/versions/728c362ec4d7/schema)