Webhooks

Webhooks são a forma recomendada de receber atualizações da API. Assim que um evento ocorre, seja um pix recebido, um boleto pago, uma transferência enviada, a Delfinance faz uma requisição POST para a URL que você registrou, entregando os dados do evento em tempo real.

Prefira webhooks a polling. A API prioriza a entrega dos webhooks antes de qualquer outra resposta, garantindo que você receba a atualização o mais rápido possível.

Registrar um webhook

POST https://apisandbox.delbank.com.br/baas/api/v1/webhooks

{
  "eventType": "PIX_RECEIVED",
  "url": "https://seuservidor.com.br/webhooks/pix",
  "authorizationScheme": "BEARER",
  "authorization": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Campos

Campo	Tipo	Obrigatório	Descrição
`eventType`	`enum`	Sim	Tipo de evento a monitorar. Veja a tabela de eventos abaixo.
`url`	`string`	Sim	URL do seu servidor que receberá os eventos via `POST`
`authorizationScheme`	`enum`	Não	Esquema de autenticação: `BASIC`, `BEARER`, `HEADER` ou `NONE`
`authorization`	`string`	Não	Valor enviado no header `Authorization` para autenticar a chamada no seu servidor

Validação da URL

A URL informada deve seguir estas regras:

Começar com http:// ou https://
Conter um domínio válido (ex: example.com)
Domínio com no mínimo 1 e no máximo 256 caracteres
TLD (.com, .br, etc.) com 1 a 6 caracteres
Pode incluir path, query params e fragmentos

Esquemas de autenticação

Esquema	Como funciona
`NONE`	Sem autenticação — use apenas em ambiente de testes
`BASIC`	Envia `Authorization: Basic <authorizationValue>`
`BEARER`	Envia `Authorization: Bearer <authorizationValue>`
`HEADER`	Envia o valor de `authorization` diretamente no header `Authorization`

Gerenciar webhooks

Método	Endpoint	Descrição
`GET`	`/baas/api/v1/webhooks`	Lista todos os webhooks cadastrados pela API key usada
`GET`	`/baas/api/v1/webhooks/:id`	Consulta um webhook específico por ID
`PATCH`	`/baas/api/v1/webhooks/:id`	Atualiza um webhook (mesmo payload do cadastro)
`DELETE`	`/baas/api/v1/webhooks/:id`	Remove um webhook cadastrado

Tipos de evento

Evento	Descrição	Página
`PIX_RECEIVED`	Pix creditado na conta	Webhooks Pix
`PIX_PAYMENT_UPDATED`	Atualização de status de Pix enviado	Webhooks Pix
`PIX_REFUNDED`	Devolução Pix recebida	Webhooks Pix
`PIX_REFUND_PAYMENT_UPDATED`	Erro em devolução Pix enviada	Webhooks Pix
`CHARGE_PAID`	Boleto pago e creditado	Webhooks Boleto
`INFRACTION_NOTIFICATION_CREATED`	Notificação de infração MED criada	MEDs
`INFRACTION_NOTIFICATION_UPDATED`	Notificação de infração MED atualizada	MEDs
`ACCOUNT_STATUS_UPDATED`	Mudança de status da conta	Outros Eventos
`WHITELABEL_CUSTOMER_APPROVED`	Conta whitelabel aprovada	Outros Eventos
`WHITELABEL_CUSTOMER_DOCUMENTATION_REJECTED`	Documentação whitelabel rejeitada	Outros Eventos

Próximos passos

Webhooks Pix

PIX_RECEIVED, PIX_PAYMENT_UPDATED, PIX_REFUNDED, PIX_REFUND_PAYMENT_UPDATED

Webhooks Boleto

CHARGE_PAID

MEDs

INFRACTION_NOTIFICATION_CREATED e INFRACTION_NOTIFICATION_UPDATED

Outros Eventos

Status de conta e aprovação whitelabel

Introdução

Autenticação

Receber via Pix (Pix Cash-in)

Pagar via Pix (Pix Cash-out)

Cobranças via Boleto

Split de Pagamentos

Webhooks

Registrar um webhook

Campos

Validação da URL

Esquemas de autenticação

Gerenciar webhooks

Tipos de evento

Próximos passos

Webhooks Pix

Webhooks Boleto

MEDs

Outros Eventos

​Registrar um webhook

​Campos

​Validação da URL

​Esquemas de autenticação

​Gerenciar webhooks

​Tipos de evento

​Próximos passos

Webhooks Pix

Webhooks Boleto

MEDs

Outros Eventos

Registrar um webhook

Campos

Validação da URL

Esquemas de autenticação

Gerenciar webhooks

Tipos de evento

Próximos passos