Webhooks - Aira

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:

Acesse Configurações → Webhooks
Informe a URL do seu endpoint
Selecione os eventos que deseja receber
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

Evento	Descrição
`invoice.status-updated`	Disparado 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

Verifique o header X-Webhook-Token

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

Parse o payload JSON

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

Processe o evento

Atualize seus sistemas conforme o tipo de evento recebido.

Responda com status 2XX

Confirme o recebimento para evitar retentativas automáticas.

Próximos passos

Autenticação — configure sua chave de API
Respostas de erro — entenda o formato de erros

​Como funciona

​Configuração

​Autenticação

​Eventos disponíveis

​Estrutura do payload

​invoice.status-updated

​Retentativas

​Verificação de webhooks

​Próximos passos