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
`integration.inbound-failed`	Disparado quando um webhook de integração externa falha ao ser processado

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>"
    },
    "contract": "<{ id: string } | null>",
    "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 O campo contract traz o contrato que originou a fatura — use o id em GET /v1/contracts/{id} para buscar o contrato completo. Ele é null em faturas avulsas, que não nascem de um contrato.

integration.inbound-failed

Disparado quando um evento recebido de uma integração (por exemplo, um negócio movido no HubSpot) falha em todas as tentativas de processamento e é marcado como falho. É o sinal para corrigir o dado na origem e reenviar o evento:

{
  "app": "<IntegrationApp>",
  "event": "<string>",
  "payload": { },
  "attemptCount": "<number>",
  "receivedAt": "<string>",
  "error": {
    "code": "<string | null>",
    "message": "<string | null>",
    "userDetails": "<object | null>"
  }
}

app — integração de origem do evento (ex: hubspot)
event — evento de entrada original (ex: deal.propertyChange)
payload — payload original recebido da integração
attemptCount — total de tentativas de processamento esgotadas
receivedAt — quando o evento original foi recebido (ISO 8601)
error — o erro da última tentativa: code identifica o tipo (ex: invalid_tax_id), message descreve o problema e userDetails traz os dados relevantes (ex: o CNPJ rejeitado)

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

​integration.inbound-failed

​Retentativas

​Verificação de webhooks

​Próximos passos