Webhooks bill.pt (Automação e Integrações)

Utilize os webhooks para comunicar com serviços externos quando cria, anula ou paga um documento automaticamente. Os webhooks podem ser utilizados para criar automações e integrar com qualquer sistema.

Resumo rápido: Ative os Webhooks em Configurações, crie um novo webhook (ação + destino) e valide o pedido recebido usando o header X-Webhook-Secret.

Como funciona

Sempre que ocorrer uma ação configurada, o bill.pt enviará um POST request para o seu endpoint (destino) com os dados do evento. Cada webhook inclui headers para identificar a ação e permitir validação de autenticidade.

Headers enviados em todos os webhooks
  • X-Webhook-Action: por exemplo documento.criado
  • X-Webhook-Secret: CHAVE_SECRETA_PARA_VALIDAR_O_WEBHOOK

Instalar e ativar

  1. Aceder às Configurações
    Visite Configurações (canto superior direito).
    No menu lateral direito, clique em Webhooks.
  2. Criar um novo webhook
    Clique no botão “Criar novo webhook” (azul).
    Criar novo webhook no bill.pt
    Imagem 1 — Botão “Criar novo webhook”.
  3. Escolher a ação e o destino
    Selecione a ação que dispara o webhook e indique o URL de destino (endpoint) que irá receber o POST.
    Escolher ação e destino do webhook
    Imagem 2 — Ação que gera o webhook e URL de destino.
  4. Consultar o histórico
    Pode ver o histórico de envios e resultados ao clicar na aba Histórico.
    Histórico de webhooks
    Imagem 3 — Histórico dos webhooks.

Validação do secret (exemplo PHP)

Para garantir que o webhook veio do bill.pt, valide o header X-Webhook-Secret e compare com a chave que configurou. O body chega via POST (normalmente JSON). 

<?php
// Exemplo simples (PHP puro) para receber webhooks bill.pt
// Coloque este ficheiro num endpoint público, ex: https://seusite.com/webhook-billpt.php

// 1) Define a tua chave esperada (guarda isto em env/secret manager, não hardcode em produção)
$expectedSecret = 'COLOQUE_AQUI_A_SUA_CHAVE_SECRETA';

// 2) Ler headers (funciona bem em Apache/Nginx + PHP-FPM)
$headers = function_exists('getallheaders') ? getallheaders() : [];

// Normaliza o nome do header (pode variar em alguns servidores)
$action = $headers['X-Webhook-Action'] ?? $headers['x-webhook-action'] ?? null;
$secret = $headers['X-Webhook-Secret'] ?? $headers['x-webhook-secret'] ?? null;

// 3) Validar secret
if (!$secret || !hash_equals($expectedSecret, $secret)) {
  http_response_code(401);
  echo json_encode(['ok' => false, 'error' => 'Invalid webhook secret']);
  exit;
}

// 4) Ler body (POST)
$raw = file_get_contents('php://input');
$data = json_decode($raw, true);

// Se não for JSON, guarda raw para debug
if (json_last_error() !== JSON_ERROR_NONE) {
  $data = ['raw' => $raw];
}

// 5) Processar por ação
switch ($action) {
  case 'documento.criado':
    // TODO: tratar documento criado
    break;

  case 'documento.anulado':
    // TODO: tratar documento anulado
    break;

  case 'documento.pago':
    // TODO: tratar documento pago
    break;

  default:
    // Ação desconhecida — opcionalmente logar
    break;
}

// 6) Responder 200 para confirmar receção
http_response_code(200);
echo json_encode(['ok' => true]);

Boas práticas

  • Responda rápido (200 OK) e processe em background se necessário (fila/job) para evitar timeouts.
  • Registe logs de X-Webhook-Action e do body para debug (sem dados sensíveis).
  • Se mudar a chave secreta, atualize-a no seu endpoint.
  • Garanta que o endpoint usa HTTPS.
Icon