Skip to main content
Webhooks permitem que sua aplicação receba notificações em tempo real quando eventos ocorrem na Aira — como mudanças de status em faturas.

​
Como funciona

Quando um evento assinado ocorre, a Aira envia uma requisição POST para o endpoint configurado com os detalhes do evento. Sua aplicação processa a notificação e responde com um status 2XX para confirmar o recebimento.

​
Configuração

Para receber webhooks, configure um endpoint no Dashboard:
  1. Acesse Configurações → Webhooks
  2. Informe a URL do seu endpoint
  3. Selecione os eventos que deseja receber
  4. Opcionalmente, defina um token de autenticação para validar as requisições

​
Autenticação

Se um token for configurado, a Aira o envia no header X-Webhook-Token em toda requisição. Seu endpoint deve verificar o valor deste header antes de processar o payload. 
POST /your-endpoint HTTP/1.1
Host: yourapp.com
Content-Type: application/json
X-Webhook-Token: seu_token_secreto

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "event": "invoice.status-updated",
  "payload": { ... }
}

​
Eventos disponíveis

EventoDescrição
invoice.status-updatedDisparado quando o status de uma fatura é alterado

​
Estrutura do payload

Toda requisição de webhook segue esta estrutura: 
{
  "id": "<UUID>",
  "event": "<EventType>",
  "payload": {
    // dados específicos do evento
  }
}
  • id — identificador único do webhook
  • event — tipo do evento (ex: invoice.status-updated)
  • payload — dados específicos do evento

​
invoice.status-updated

Disparado quando o status de uma fatura é alterado: 
{
  "invoice": {
    "id": "<string>",
    "customer": {
      "id": "<string>",
      "name": "<string>",
      "externalId": "<string>"
    },
    "billingAccount": {
      "businessName": "<string>",
      "taxId": "<string>",
      "taxIdType": "<TaxIdType>"
    },
    "invoiceNumber": "<string>",
    "invoiceDate": "<string>",
    "dueDate": "<string | null>",
    "totalAmount": "<number>",
    "status": "<InvoiceStatus>"
  },
  "changes": {
    "oldStatus": "<InvoiceStatus>",
    "newStatus": "<InvoiceStatus>"
  }
}
Valores de InvoiceStatus: open, in_review, issued, synced, pending, paid, overdue, canceled, failed

​
Retentativas

Se o seu endpoint não responder com status 2XX, a Aira tenta reenviar automaticamente até 3 vezes. O código de resposta de cada tentativa é registrado para diagnóstico. Webhooks que falharam após todas as tentativas podem ser reprocessados manualmente pelo Dashboard em Configurações → Webhooks.

​
Verificação de webhooks

1

Verifique o header X-Webhook-Token

Compare o valor do header com o token que você configurou. Processe a requisição apenas se coincidirem.
2

Parse o payload JSON

Extraia os campos event e payload do corpo da requisição.
3

Processe o evento

Atualize seus sistemas conforme o tipo de evento recebido.
4

Responda com status 2XX

Confirme o recebimento para evitar retentativas automáticas.

​
Próximos passos