Skip to main content
POST
Esta rota cadastra um endpoint de webhook: a URL do seu servidor que vai receber, por POST, os eventos de cobrança, de assinatura e de saque de uma conta. Pela API, você escolhe quais eventos o endpoint recebe. Na conta master do Connect, um único endpoint pode receber também os eventos de todas as subcontas.

Quando usar

Antes de chamar

  • Use a chave secreta (sk_) em Basic (Credenciais e ambientes). A chave age com as permissões do usuário que a gerou: um perfil sem permissão de webhooks recebe 403 Acesso negado.
  • Tenha o id da conta que vai receber os eventos. Para uma subconta, consulte Listar subcontas.
  • A URL precisa ser um endereço http ou https público. Endereços internos e reservados são recusados. Use HTTPS.
  • O mesmo endpoint recebe eventos de teste e de produção. Veja Teste e produção.
O corpo desta rota usa snake_case (enabled_events, include_submerchants), diferente do resto da API. Os nomes em camelCase (enabledEvents) não são reconhecidos no corpo, embora a listagem devolva os campos em camelCase.

Parâmetros de consulta

string
required
Id da conta dona do endpoint: a sua própria conta ou, para a conta master, uma das subcontas que ela criou. Obrigatório para credenciais de conta: sem ele, a resposta é 403. Ex.: 3Fq9TzL2mWc8VbN1xR7pK4hJ6sD.

Corpo da requisição

string
required
Endereço http ou https público que vai receber os eventos. Ex.: https://meusite.com.br/webhooks/finvia.
string[]
required
Lista de eventos que o endpoint recebe. Lista vazia ([]) recebe todos. Nomes possíveis:
  • Cobrança: charge.created, charge.pending, charge.paid, charge.refused, charge.failed, charge.refunded, charge.pre_chargeback, charge.blocked.
  • Assinatura: subscription.created, subscription.activated, subscription.renewed, subscription.payment_failed, subscription.cancelled, subscription.expired.
  • Saque: payout.approved, payout.rejected.
O charge.updated é entregue só ao postbackUrl da cobrança. Incluí-lo aqui não tem efeito.
boolean
Só para conta master com Connect habilitado. Com true, o endpoint passa a receber também os eventos de cobrança, assinatura e saque das subcontas. O merchant_id (ou merchantId) de cada payload indica a subconta de origem. Em conta sem Connect, a resposta é 400.

Respostas

A resposta de sucesso é 201 sem corpo: a API não devolve o id do endpoint. Para obter o id (necessário para editar ou excluir), use GET /v1/webhook-endpoints com o mesmo merchantId. Mensagens literais da API. Elas misturam português e inglês e podem mudar: trate o erro pelo código HTTP, não pelo texto.

Erros comuns

Veja também

Listar endpoints

Obtenha o id e confira os eventos de cada endpoint.

Atualizar endpoint

Troque a URL ou os eventos.

Webhooks: visão geral

Quem recebe cada evento, formatos e deduplicação.

Catálogo de eventos

Todos os eventos e quando são enviados.