Skip to main content
Em resumo
Webhooks enviam notificações em tempo real para seu servidor quando eventos ocorrem—depósitos, saques, swaps e mais. Em vez de consultar a API, seu servidor recebe atualizações instantâneas quando transações são concluídas.

Pré-requisitos

Antes de configurar webhooks, certifique-se de ter:
1

Chave API

Obtenha sua chave API no Painel da Blockradar. Navegue até Developers para gerar uma.
2

Endpoint de Webhook

Crie um endpoint POST no seu servidor que possa receber payloads JSON e retornar uma resposta 200 OK.
3

URL HTTPS (Produção)

Para produção, sua URL de webhook deve usar HTTPS. Para testes locais, use ferramentas como ngrok ou webhook.site.
4

Carteira Mestra

Configure sua URL de webhook na sua carteira mestra via painel.

Como Funciona

Quando você faz uma solicitação a um endpoint de API, espera obter uma resposta quase imediata. No entanto, algumas solicitações podem levar muito tempo para processar, o que pode levar a erros de timeout. Para evitar um erro de timeout, uma resposta pendente é retornada. Como seus registros precisam ser atualizados com o estado final da solicitação, você precisa:
  1. Fazer uma solicitação de atualização (popularmente conhecida como polling) ou,
  2. Ouvir eventos usando uma URL de webhook.
Dica Útil
Recomendamos que você use webhook para fornecer valor aos seus clientes em vez de usar callbacks ou polling. Com callbacks, não temos controle sobre o que acontece no lado do cliente. Nem você. Callbacks podem falhar se a conexão de rede no dispositivo de um cliente falhar ou estiver fraca ou se o dispositivo desligar após uma transação.

Polling vs Webhooks

Polling requer fazer uma solicitação GET em intervalos regulares para obter o status final de uma solicitação. Por exemplo, quando você emite um endereço para um cliente para depósitos, você continua fazendo uma solicitação de transações vinculadas ao endereço até encontrar uma. Com webhooks, o servidor de recursos, Blockradar neste caso, envia atualizações para o seu servidor quando o status da sua solicitação muda. A mudança no status de uma solicitação é conhecida como um evento. Você normalmente ouvirá esses eventos em um endpoint POST chamado URL de webhook. A tabela abaixo destaca algumas diferenças entre polling e webhooks:

Criar uma URL de webhook

Uma URL de webhook é simplesmente um endpoint POST para o qual um servidor de recursos envia atualizações. A URL precisa analisar uma solicitação JSON e retornar um 200 OK:
Quando sua URL de webhook recebe um evento, ela precisa analisar e reconhecer o evento. Reconhecer um evento significa retornar um 200 OK no cabeçalho HTTP. Sem um 200 OK no cabeçalho de resposta, continuaremos enviando eventos pelas próximas 2 horas e 35 minutos:
  • Tentaremos enviar webhooks 5 vezes com um atraso crescente entre cada tentativa, começando com 5 minutos e aumentando exponencialmente até 80 minutos. A duração total dessas 5 tentativas abrangerá aproximadamente 2 horas e 35 minutos.
Evite tarefas de longa duração
Se você tiver tarefas de longa duração em sua função de webhook, você deve reconhecer o evento antes de executar as tarefas de longa duração. Tarefas de longa duração levarão a um timeout de solicitação e uma resposta de erro automática do seu servidor. Sem uma resposta 200 OK, tentamos novamente conforme descrito no parágrafo acima.

Testando Webhooks Localmente

Durante o desenvolvimento, você pode configurar sua URL de webhook no ambiente de carteira principal TEST para um endereço local, como http://localhost ou 127.0.0.1. Para expor seu servidor local à internet para fins de teste, considere usar uma ferramenta como ngrok ou webhook.site. Essas ferramentas permitem que você veja como é a carga útil do webhook e simule eventos de webhook localmente antes de implantar seu aplicativo em um ambiente ativo. Usando essas ferramentas, você pode garantir que sua integração de webhook esteja funcionando corretamente e lidar com quaisquer problemas em um ambiente local e controlado antes de passar para produção.

Reenviar Webhook de Transação

No caso em que por algum motivo você não recebe o webhook de transação e o tempo de backoff expirou, fornecemos uma API que você pode usar para reenviar um webhook de transação
Use com cautela!
Como isso pode levar ao processamento de transações já concluídas, certifique-se de ter validação adequada em vigor ao usar este endpoint.

Verificar origem do evento

Como sua URL de webhook está disponível publicamente, você precisa verificar se os eventos se originam do Blockradar e não de um agente mal-intencionado. Existem duas maneiras de garantir que os eventos para sua URL de webhook sejam do Blockradar:
  1. Validação de assinatura (recomendado)

Validação de assinatura

Eventos enviados do Blockradar carregam o cabeçalho x-blockradar-signature. O valor deste cabeçalho é uma assinatura HMAC SHA512 da carga útil do evento assinada usando sua chave secreta. A verificação da assinatura do cabeçalho deve ser feita antes de processar o evento:

Checklist de Entrada em Produção

Agora que você criou com sucesso sua URL de webhook, aqui estão algumas maneiras de garantir que você tenha uma experiência agradável:
  • Adicione a URL do webhook em suas Carteiras Principais no painel Blockradar
  • Certifique-se de que sua URL de webhook esteja disponível publicamente (URLs localhost não podem receber eventos)
  • Se estiver usando .htaccess, lembre-se de adicionar a barra / final à URL
  • Teste seu webhook para garantir que você está recebendo o corpo JSON e retornando uma resposta HTTP 200 OK
  • Se sua função de webhook tiver tarefas de longa duração, você deve primeiro reconhecer o recebimento do webhook retornando um 200 OK antes de prosseguir com as tarefas de longa duração
  • Se não recebermos uma resposta HTTP 200 OK de seus webhooks, sinalizamos como uma tentativa falhada
  • Tentaremos enviar webhooks 5 vezes com um atraso crescente entre cada tentativa, começando com 5 minutos e aumentando exponencialmente até 80 minutos. A duração total dessas 5 tentativas abrangerá aproximadamente 2 horas e 35 minutos.

Tipos de eventos

Aqui estão os eventos que atualmente levantamos. Adicionaremos mais a esta lista à medida que nos conectarmos a mais ações no futuro.

Exemplos de Eventos

Abaixo estão exemplos de cargas úteis de webhook para alguns dos eventos mais comuns:

Complete Event List

Transaction Types and Statuses

Transaction Types

The following transaction types are used in webhook payloads:

Transaction Statuses

The following statuses indicate the current state of a transaction:
These transaction types and statuses are used in the type and status fields of webhook payloads to help you understand what kind of transaction occurred and its current state.
Happy hacking! ❤️