Webhooks

Receba resultados em tempo real

Webhooks são a forma como a API da Faroway entrega os resultados das consultas de score. Registre uma URL e receba um POST com o resultado assim que o processamento for concluído.

Registrar webhook#

POST/v1/webhooks

Registra ou atualiza o webhook para o ambiente da chave de API usada. Cada ambiente (dev/prod) suporta um webhook ativo.

Upsert

Se já existir um webhook para o ambiente, ele será atualizado com a nova URL e eventos. Não é necessário deletar antes de atualizar.

Corpo da requisição#

Parâmetro	Tipo	Obrigatório	Descrição
`url`	string	sim	URL HTTPS ou HTTP que receberá os webhooks. Deve resolver para um IP público (não pode ser localhost ou IP privado).
`events`	string[]	sim	Array com os eventos desejados: "score.completed" e/ou "score.failed". Não pode ser vazio.

Exemplo

json

{
  "url": "https://yourapp.com/webhooks/faroway",
  "events": [
    "score.completed",
    "score.failed"
  ]
}

cURL

bash

curl -X POST https://api.faroway.tech/v1/webhooks \
  -H "Authorization: Bearer sua_chave_de_api" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://yourapp.com/webhooks/faroway",
  "events": [
    "score.completed",
    "score.failed"
  ]
}'

Resposta — 200 OK#

json

{
  "webhook": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "environment": "dev",
    "url": "https://yourapp.com/webhooks/faroway",
    "events": [
      "score.completed",
      "score.failed"
    ],
    "created_at": "2026-03-07T10:00:00Z",
    "updated_at": "2026-03-07T10:00:00Z"
  }
}

Campos da resposta

Campo	Tipo	Descrição
`webhook.id`	string (UUID)	Identificador único do webhook.
`webhook.environment`	"dev" \| "prod"	Ambiente do webhook (determinado pela chave de API usada).
`webhook.url`	string	URL registrada.
`webhook.events`	string[]	Eventos habilitados.
`webhook.created_at`	string (ISO 8601)	Data de criação.
`webhook.updated_at`	string (ISO 8601)	Data da última atualização.

Validação de URL#

A URL do webhook é validada no momento do registro. As seguintes restrições se aplicam:

Deve usar protocolo https ou http
Não pode apontar para localhost
O hostname deve resolver para um IP público (IPs privados como 10.x.x.x, 192.168.x.x, 172.16-31.x.x são rejeitados)
O DNS do hostname deve resolver com sucesso

Ambiente de desenvolvimento

Para testes locais, use um serviço de tunneling como ngrok ou Cloudflare Tunnel para expor sua máquina local com uma URL pública.

Eventos suportados#

Evento	Quando é disparado
`score.completed`	A consulta foi processada com sucesso. O payload inclui o score, nível de risco e detalhamento de processos.
`score.failed`	A consulta não pôde ser processada. O payload inclui um código e mensagem de erro.

Payloads do webhook#

score.completed#

json

{
  "event": "score.completed",
  "request_id": "req_8f2b4a2d",
  "external_id": "customer-123",
  "status": "completed",
  "result": {
    "document": "12345678909",
    "score": 93,
    "risk_level": "low",
    "cases": {
      "total": 1,
      "open": 0,
      "closed": 1
    },
    "case_breakdown": {
      "labor": 0,
      "civil": 1,
      "criminal": 0,
      "tax": 0
    },
    "completed_at": "2026-03-07T12:00:08Z"
  }
}

Campo	Tipo	Descrição
`event`	"score.completed"	Tipo do evento.
`request_id`	string	ID da consulta original.
`external_id`	string \| null	Seu identificador externo, se enviado na consulta.
`status`	"completed"	Status final da consulta.
`result`	object	Resultado completo com score, risk_level, cases e case_breakdown.

Para detalhes sobre os campos do result, veja a página de consulta de score.

score.failed#

json

{
  "event": "score.failed",
  "request_id": "req_1ac93e44",
  "external_id": "customer-456",
  "status": "failed",
  "error": {
    "code": "mock_processing_error",
    "message": "The request could not be processed for this document."
  }
}

Campo	Tipo	Descrição
`event`	"score.failed"	Tipo do evento.
`request_id`	string	ID da consulta original.
`external_id`	string \| null	Seu identificador externo, se enviado.
`status`	"failed"	Status final da consulta.
`error.code`	string	Código do erro.
`error.message`	string	Descrição legível do erro.

Comportamento operacional#

Timeout: A Faroway aguarda até 10 segundos por uma resposta do seu endpoint. Se o tempo for excedido, o webhook é marcado como falho.
Status esperado: Retorne um status HTTP 2xx para confirmar o recebimento. Qualquer outro status é tratado como falha na entrega.
Content-Type: Os webhooks são enviados como application/json via POST.
Um webhook por ambiente: Cada ambiente (dev/prod) suporta apenas um webhook ativo por vez. Registrar um novo sobrescreve o anterior.

Idempotência

Embora raro, seu endpoint pode receber o mesmo evento mais de uma vez em cenários de rede. Use o campo request_id para garantir processamento idempotente.

Erros possíveis#

Field url must be a valid URL.— URL inválida

Field url must use http or https.— Protocolo não suportado

Webhook hosts cannot point to localhost.— URL apontando para localhost

Webhook hosts must resolve to a public IP address.— IP privado detectado

Could not resolve the webhook host.— DNS não resolveu

Field events must be a non-empty array.— events vazio ou não é array

Invalid event. Use score.completed or score.failed.— Evento não suportado