Skip to main content
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

CampoTipoObrigatórioDescrição
eventTypeenumSimTipo de evento a monitorar. Veja a tabela de eventos abaixo.
urlstringSimURL do seu servidor que receberá os eventos via POST
authorizationSchemeenumNãoEsquema de autenticação: BASIC, BEARER, HEADER ou NONE
authorizationstringNãoValor 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

EsquemaComo funciona
NONESem autenticação — use apenas em ambiente de testes
BASICEnvia Authorization: Basic <authorizationValue>
BEAREREnvia Authorization: Bearer <authorizationValue>
HEADEREnvia o valor de authorization diretamente no header Authorization

​
Gerenciar webhooks

MétodoEndpointDescrição
GET/baas/api/v1/webhooksLista todos os webhooks cadastrados pela API key usada
GET/baas/api/v1/webhooks/:idConsulta um webhook específico por ID
PATCH/baas/api/v1/webhooks/:idAtualiza um webhook (mesmo payload do cadastro)
DELETE/baas/api/v1/webhooks/:idRemove um webhook cadastrado

​
Tipos de evento

EventoDescriçãoPágina
PIX_RECEIVEDPix creditado na contaWebhooks Pix
PIX_PAYMENT_UPDATEDAtualização de status de Pix enviadoWebhooks Pix
PIX_REFUNDEDDevolução Pix recebidaWebhooks Pix
PIX_REFUND_PAYMENT_UPDATEDErro em devolução Pix enviadaWebhooks Pix
CHARGE_PAIDBoleto pago e creditadoWebhooks Boleto
INFRACTION_NOTIFICATION_CREATEDNotificação de infração MED criadaMEDs
INFRACTION_NOTIFICATION_UPDATEDNotificação de infração MED atualizadaMEDs
ACCOUNT_STATUS_UPDATEDMudança de status da contaOutros Eventos
WHITELABEL_CUSTOMER_APPROVEDConta whitelabel aprovadaOutros Eventos
WHITELABEL_CUSTOMER_DOCUMENTATION_REJECTEDDocumentação whitelabel rejeitadaOutros 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