EverbridgedevelopersOpenAPI ↗
GUIAS DE INTEGRAÇÃO

Webhooks: pagamentos, clientes e KYC

Receba eventos de recebimento, mudanças do cadastro, KYC, termos e habilitações.

Cadastrar e testar

Seu backend expõe uma URL pública HTTPS e cadastra POST /v1/webhooks com sua chave Everbridge e Idempotency-Key. Use o escopo webhooks:write para configurar e webhooks:read para consultar. São permissões específicas: uma chave antiga não as recebe automaticamente. O destino pertence à organização, compartilhado entre suas chaves autorizadas, e recebe os pagamentos de seus clientes finais.

{
  "url": "https://app.example.com/webhooks/everbridge",
  "event_categories": [
    "virtual_account.activity",
    "transfer",
    "wallet.activity"
  ]
}

Guarde o id do endpoint e o signing_secret retornado. O segredo é próprio do webhook, separado da chave de API, e não aparece nas consultas. Repetir a mesma intenção com a mesma chave de idempotência recupera o resultado original. Há limite de cinco endpoints. Não inclua segredos na URL; eles podem aparecer no histórico de configuração.

Implemente a validação de assinatura e envie POST /v1/webhooks/{id}/test com {}. O teste tem event_type=webhook.test, test=true e nenhum pagamento. Não gere crédito com testes. Consulte GET /v1/webhooks/{id}/deliveries para confirmar a entrega.

Categorias disponíveis

As cinco categorias abaixo podem compartilhar o mesmo endpoint e o mesmo segredo de assinatura. Consulte GET /v1/webhooks/{id} para conferir a seleção atual; uma categoria disponível na API só é entregue quando está incluída em event_categories nesse endpoint.

CategoriaInformação principal
virtual_account.activityEtapas do depósito na conta virtual, em event_object.type.
transferMudanças da transferência, com estado em event_object.state.
wallet.activityAtividades da wallet, incluindo depósitos cripto; a origem fica em event_object.source.from_address, quando disponível.
customerEstado do cadastro, aceite dos termos e habilitações resumidas.
kyc_linkEstados do KYC e dos termos associados ao link.

Novos endpoints sem seleção explícita incluem as três categorias de pagamentos. customer e kyc_link exigem seleção explícita. Endpoints existentes preservam sua configuração.

Clientes, KYC, termos e habilitações

Selecione customer e kyc_link em event_categories para receber mudanças de cadastro no mesmo endpoint de pagamentos, usando a mesma assinatura HMAC. Elas não são adicionadas automaticamente a assinaturas antigas. Para receber todas as cinco categorias, use PATCH /v1/webhooks/{id} com uma nova Idempotency-Key:

{
  "event_categories": [
    "virtual_account.activity",
    "transfer",
    "wallet.activity",
    "customer",
    "kyc_link"
  ]
}

A lista substitui a seleção anterior: inclua todas as categorias que deseja manter. URL, status ativo/pausado, signing_secret e secret_version permanecem iguais. Não é necessário trocar a chave da API ou chamar rotate-secret. Para gerenciar pela API, a chave precisa de webhooks:write; para consultar configurações e entregas, webhooks:read. Um 403 insufficient_scope deve ser tratado com a equipe responsável pela sua chave, preservando o endpoint existente.

Na categoria customer, event_object.id é o customer_id. Leia status, has_accepted_terms_of_service e endorsements[].name/status. Tipos de evento incluem customer.created, customer.updated, customer.updated.status_transitioned e customer.deleted. Uma habilitação pode mudar em customer.updated mesmo com cadastro já ativo; não filtre apenas transições de status.

{
  "api_version": "v1",
  "event_id": "evt_CUSTOMER_EXEMPLO",
  "event_category": "customer",
  "event_type": "customer.updated.status_transitioned",
  "event_created_at": "2026-10-21T12:00:00.000Z",
  "livemode": true,
  "test": false,
  "event_object": {
    "id": "cus_EXEMPLO",
    "type": "individual",
    "status": "active",
    "has_accepted_terms_of_service": true,
    "endorsements": [
      {
        "name": "crypto_to_crypto",
        "status": "approved"
      },
      {
        "name": "pix",
        "status": "approved"
      }
    ],
    "updated_at": "2026-10-21T12:00:00.000Z"
  }
}

Na categoria kyc_link, event_object.id identifica o link e customer_id relaciona o titular, quando disponível. Leia kyc_status e tos_status. Tipos incluem kyc_link.created, kyc_link.updated e kyc_link.updated.status_transitioned.

{
  "api_version": "v1",
  "event_id": "evt_KYC_EXEMPLO",
  "event_category": "kyc_link",
  "event_type": "kyc_link.updated.status_transitioned",
  "event_created_at": "2026-10-21T12:00:00.000Z",
  "livemode": true,
  "test": false,
  "event_object": {
    "id": "kyc_EXEMPLO",
    "customer_id": "cus_EXEMPLO",
    "type": "individual",
    "kyc_status": "approved",
    "tos_status": "approved",
    "created_at": "2026-10-20T12:00:00.000Z"
  }
}

Para avisar o lojista que a verificação foi aprovada, use kyc_status: "approved". Para liberar uma operação financeira, confira também o customer active, o aceite dos termos e a habilitação da rota approved. Início ou envio de documentos não significa aprovação. Eventos podem chegar repetidos ou fora de ordem: deduplique por event_id e confirme o estado atual por GET antes de liberar serviços ou regredir um cadastro. Um evento de exclusão não representa aprovação. O feed /v1/events continua disponível para recuperação.

Essas notificações levam IDs, estados e habilitações resumidas. Não contêm nome, e-mail, CPF, endereço, fotos, documentos, selfie, URLs de KYC/termos, motivos internos ou o dossiê completo. Campos adicionais podem faltar conforme o evento; para requisitos e pendências, consulte o cadastro autorizado pela API. As novas categorias recebem somente eventos gravados após sua ativação; não há reenvio automático de histórico.

Qual evento libera a antecipação?

Para um Pix na conta virtual, filtre event_category=virtual_account.activity e event_object.type=funds_received. O evento é enviado assim que chega à Everbridge e entra na fila de entrega; não aguarda conversão ou payment_processed. A latência depende da confirmação do pagamento, da chegada do evento e da disponibilidade do seu endpoint; não existe garantia de aviso no exato instante em que o pagador confirma o Pix.

{
  "api_version": "v1",
  "event_id": "evt_EXEMPLO",
  "event_category": "virtual_account.activity",
  "event_type": "virtual_account.activity.created",
  "event_created_at": "2026-10-06T12:00:00.000Z",
  "livemode": true,
  "test": false,
  "event_object": {
    "id": "activity_EXEMPLO",
    "type": "funds_received",
    "customer_id": "cus_EXEMPLO",
    "virtual_account_id": "va_EXEMPLO",
    "deposit_id": "dep_EXEMPLO",
    "amount": "90.00",
    "currency": "brl",
    "source": {
      "payment_rail": "pix"
    }
  }
}

event_type descreve a criação ou atualização do evento; a etapa financeira da conta virtual fica em event_object.type. Em transferências (event_category=transfer), consulte event_object.state. O mesmo webhook recebe etapas posteriores e devoluções. Campos e estados adicionais podem surgir; preserve desconhecidos para conciliação, sem tratá-los como sucesso.

funds_received confirma recebimento, não liquidação final nem irreversibilidade. Liberar crédito nessa etapa é uma política de antecipação da sua plataforma. Trate eventos de revisão, falha e devolução, inclusive após o recebimento. payment_processed confirma processamento ao destino.

Creditar o valor correto uma única vez

  1. Valide assinatura e horário, e rejeite teste ou ambiente incompatível.
  2. Associe customer_id e virtual_account_id ao cliente da sua plataforma. Não identifique o pagador apenas pelo valor.
  3. No recebimento Pix, confira amount e currency=brl. Preserve strings decimais; use centavos inteiros ou uma biblioteca decimal. R$ 90 recebidos em uma cobrança de R$ 100 permitem contabilizar R$ 90, deixando R$ 10 pendentes. Não use o valor esperado da cobrança.
  4. Se faltarem valor, moeda de entrada ou deposit_id, mantenha pendente e reconcilie pelo histórico. Não estime BRL usando o montante convertido. Em transferências, amount pode representar o valor solicitado; valide o recebimento real no recurso e comprovante antes de creditar.
  5. Em uma transação do seu banco, persista o evento com unicidade por event_id. Faça o lançamento com unicidade por organização + conta virtual + deposit_id. Atualizações, retentativas e payment_processed do mesmo depósito não geram um segundo crédito.
  6. Responda 2xx após gravar de forma durável. Se o processamento for assíncrono, confirme somente depois de persistir o evento na sua fila. Uma resposta duplicada válida também deve ser 2xx.

Não há ordem garantida entre eventos. Um recebimento entregue com atraso não deve reabrir crédito de um depósito já devolvido. Consulte o histórico quando houver conflito e preserve os estágios separados do lançamento contábil. O webhook não cria sua cobrança e não informa que alguém “não pagou”; sua aplicação compara recebimentos e vencimentos.

Depósitos cripto em wallet de tesouraria

Assine wallet.activity para receber as atividades das wallets vinculadas à sua organização. event_object.wallet_id identifica a wallet que recebeu a atividade. Uma entrada direta on-chain usa type=direct_deposit; outras entradas podem usar deposit. Saídas e devoluções são atividades diferentes: não credite qualquer evento desta categoria.

{
  "api_version": "v1",
  "event_id": "evt_WALLET_EXEMPLO",
  "event_category": "wallet.activity",
  "event_type": "wallet.activity.created",
  "event_created_at": "2026-10-12T12:00:00.000Z",
  "livemode": true,
  "test": false,
  "event_object": {
    "id": "activity_WALLET_EXEMPLO",
    "wallet_id": "wal_TESOURARIA",
    "type": "direct_deposit",
    "amount": "25.00",
    "available_balance": "125.00",
    "currency": "usdc",
    "source_address_status": "available",
    "source": {
      "currency": "usdc",
      "payment_rail": "tempo",
      "from_address": "ENDERECO_DA_CARTEIRA_REMETENTE"
    },
    "destination": {
      "currency": "usdc",
      "payment_rail": "tempo",
      "tx_hash": "HASH_DA_TRANSACAO"
    },
    "created_at": "2026-10-12T12:00:00.000Z"
  }
}

O endereço remetente fica em event_object.source.from_address. O indicador source_address_status será available ou unavailable; na ausência de evidência, from_address será null. Para depósitos vinculados a uma transferência da própria organização, a Everbridge busca a origem na transferência quando ela falta na atividade. Se essa consulta falhar, a entrega é tentada novamente. Quando resolvido, o conteúdo é persistido para as retentativas. Não inventamos endereço com base no saldo nem usamos o endereço de destino como se fosse remetente.

source.wallet_id pode identificar a wallet remetente quando ela é um recurso da mesma organização. Em depósitos de wallets externas esse ID pode não existir. destination.tx_hash e payment_route.transfer_id são referências de conciliação quando fornecidas. A rede é informada nos dados da rota quando disponível; payment_rail=wallet é uma modalidade de carteira, não o nome de uma blockchain. Para a rede da wallet, consulte o recurso e seu campo chain.

Endereço remetente não garante identidade de usuário. Exchanges, contratos e wallets compartilhadas podem originar pagamentos de várias pessoas pelo mesmo endereço. Vincule endereços previamente verificados no seu sistema e mantenha origens desconhecidas ou ambíguas em conciliação. Depósito on-chain não torna qualquer rede ou token suportado.

Deduplique notificações por event_id e lançamentos por wallet_id + event_object.id. Criação e atualização da mesma atividade podem ter event_id diferentes. A atividade de wallet e os eventos de transfer/conta virtual podem representar o mesmo dinheiro: cruze payment_route e não faça crédito duplo. available_balance é o saldo informado nessa atividade, não o valor novo do depósito nem a soma dos recebimentos.

Confirme valor, currency, tipo, wallet e situação atual antes de liberar saldo. Para recuperar dados, use GET /v1/wallets/{id}/history ou GET /v1/customers/{customer_id}/wallets/{id}/history, com wallets:read. O histórico usa data e paginação por starting_after/ending_before; o feed mantém os dados originais disponíveis e o webhook pode complementar a origem pela transferência. O endereço pode não estar disponível em todas as rotas, especialmente entradas originalmente em fiat.

Habilitar em um webhook existente

Endpoints anteriores não são alterados automaticamente. Consulte GET /v1/webhooks/{id} e envie PATCH /v1/webhooks/{id}, com uma nova Idempotency-Key e a lista completa de categorias desejadas. O exemplo abaixo inclui wallet.activity e mantém os eventos de pagamentos, cadastro e KYC. A lista substitui a seleção atual e preserva URL, signing_secret, secret_version e estado active:

{
  "event_categories": [
    "virtual_account.activity",
    "transfer",
    "wallet.activity",
    "customer",
    "kyc_link"
  ]
}

Após o PATCH, consulte o endpoint novamente e confirme wallet.activity na seleção. Novos endpoints sem event_categories incluem as três categorias de pagamentos. A categoria acrescentada recebe somente eventos gravados depois da ativação; não há reenvio automático das atividades antigas. Prepare seu receptor para reconhecer wallet.activity e sua política de crédito antes de ativá-la.

Validar a assinatura

Enviamos X-Everbridge-Signature: t=TIMESTAMP,v1=HEX, calculado com HMAC-SHA256 sobre TIMESTAMP + "." + corpo_original, usando signing_secret como string UTF-8. O timestamp está em segundos Unix. Use comparação em tempo constante e tolerância de cinco minutos, com relógio sincronizado. A assinatura e o timestamp são recalculados a cada tentativa; não faça JSON.parse/stringify antes de verificar.

import { createHmac, timingSafeEqual } from 'node:crypto';

// rawBody precisa ser o Buffer original, antes de JSON.parse().
// secrets contém o segredo atual e, durante rotação, o anterior.
export function verifyEverbridge(rawBody, header, secrets, now = Date.now()) {
  if (!Buffer.isBuffer(rawBody) || typeof header !== 'string') return false;
  const match = /^t=(\d{10}),v1=([a-f0-9]{64})$/.exec(header);
  if (!match || Math.abs(now / 1000 - Number(match[1])) > 300) return false;
  const received = Buffer.from(match[2], 'hex');
  return secrets.some(secret => {
    const expected = createHmac('sha256', secret)
      .update(match[1] + '.').update(rawBody).digest();
    return timingSafeEqual(received, expected);
  });
}

Outros cabeçalhos: X-Everbridge-Delivery-Id, X-Everbridge-Event-Id e X-Everbridge-Secret-Version. O corpo assinado é a fonte confiável do evento; esses cabeçalhos servem para rastreio e escolha do segredo. POST /v1/webhooks/{id}/rotate-secret gera nova versão. Novas tentativas usam o novo segredo; mantenha o anterior temporariamente para entregas que já estavam em voo.

Fila, retentativas e recuperação

Eventos são persistidos antes da confirmação de recebimento. A fila retoma após reinícios. Cada entrega tem até oito tentativas automáticas. Após falhas, os intervalos são 10 segundos, 30 segundos, 2 minutos, 10 minutos, 30 minutos, 2 horas e 6 horas, contados após cada tentativa. Respostas fora de 200–299, redirecionamentos, falhas de conexão ou timeout geram nova tentativa. O limite da chamada HTTPS é 10 segundos, além de até 3 segundos para DNS. Responda rapidamente.

A entrega é ao menos uma vez dentro desse ciclo, com possibilidade de duplicatas, e não garante sucesso se seu endpoint permanecer indisponível. Após esgotar tentativas, o estado é failed. Corrija o receptor e use POST /v1/webhooks/{id}/deliveries/{delivery}/retry para abrir novo ciclo com os mesmos IDs e conteúdo. Os estados pending, delivering, retrying, delivered, failed e canceled descrevem a entrega HTTP, não o pagamento.

Pause com PATCH /v1/webhooks/{id} e {"active":false}; a fila fica guardada e continua acumulando eventos. Reativar retoma pendências. A suspensão da organização também interrompe novos envios. Excluir cancela pendências. Entregas em voo podem terminar. A URL não é editável: cadastre outro endpoint para trocar o destino. Para editar categorias, use PATCH no endpoint com event_categories; a lista substitui a seleção atual. Novas categorias começam nos eventos gravados após a ativação, sem backfill. Entregas já enfileiradas são preservadas. Mantenha a deduplicação durante mudanças de assinatura.

O cadastro recebe eventos novos, sem backfill automático. Eventos inicialmente sem vínculo só são encaminhados após identificar sua organização. Use GET /v1/events e o histórico da conta como recuperação e conciliação, deduplicando entre todas as fontes. As consultas de entregas começam pelas mais recentes e paginam com before=next_cursor.

Everbridge DevelopersAPI 1.4.14 · Português (Brasil)