Webhooks — Visão geral

Webhooks permitem que o InHire notifique seu sistema em tempo real quando algo acontece na sua conta — uma nova candidatura, a mudança de etapa de um candidato, a criação de uma requisição, e mais. Em vez de ficar consultando a API repetidamente (polling), você registra uma URL e o InHire envia uma requisição POST para ela sempre que o evento ocorre.

Aqui tratamos os termos: TALENTO, VAGA e CANDIDATO.

O conceito: registrar uma vez, receber muitas vezes

Um webhook funciona em duas fases separadas:

1. Registro (uma única vez). Você cria o webhook informando o evento e a sua URL. Essa chamada apenas registra a assinatura e devolve o webhook salvo (com um id). Ela não retorna eventos — é só a configuração.
2. Recebimento (contínuo e assíncrono). Depois, toda vez que a ação ocorre na sua conta, o InHire faz uma requisição POST independente para a sua URL com o payload do evento. O seu sistema recebe e processa.

FASE 1 — Registro (uma vez)
   Você  ──POST /integrations/webhooks──►  InHire   (responde: webhook salvo, com id)

FASE 2 — Recebimento (sempre que a ação acontece, de forma assíncrona)
   Ação na conta  ──►  InHire  ──POST {payload do evento}──►  sua URL  ──►  você processa

aviso

Criar o webhook não dispara nem retorna eventos. A resposta da criação é apenas o objeto do webhook. Os eventos chegam depois, em requisições separadas para a sua URL, cada vez que a ação correspondente acontece.

Criando um webhook

Registre o webhook informando qual evento quer ouvir e para qual URL o InHire deve enviar a notificação. Endpoint: Criar webhook.

curl -X POST https://api.inhire.app/integrations/webhooks \
  -H "Authorization: Bearer SEU_ACCESS_TOKEN" \
  -H "X-Tenant: tenantId" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Notificar mudança de etapa",
    "description": "Notifica quando um candidato muda de etapa no processo seletivo",
    "event": "JOB_TALENT_STAGE_ADDED",
    "url": "https://seu-sistema.com/webhooks/inhire",
    "headers": {
      "Authorization": "Bearer UM_SEGREDO_SEU"
    }
  }'

A resposta é o webhook salvo:

{
  "id": "id_gerado_automaticamente",
  "name": "Notificar mudança de etapa",
  "description": "Notifica quando um candidato muda de etapa no processo seletivo",
  "event": "JOB_TALENT_STAGE_ADDED",
  "url": "https://seu-sistema.com/webhooks/inhire",
  "headers": {
    "Authorization": "Bearer UM_SEGREDO_SEU"
  },
  "createdAt": "2026-06-18T12:00:00.000Z"
}

A partir daí, o webhook está ativo: o InHire passará a chamar a sua URL sempre que o evento ocorrer. O que fazer ao receber cada evento é descrito no guia do evento (ver tabela abaixo).

Campos do webhook

Campo	Obrigatório	Descrição
name	Sim	Nome para você identificar o webhook
event	Sim	Um dos 9 eventos da tabela abaixo
url	Sim	URL https do seu sistema que receberá o POST
headers	Não	Headers customizados enviados em toda chamada (use para autenticar a sua ponta)
rules	Não	Filtros para receber apenas eventos que interessam (ver abaixo)
description	Não	Texto livre de documentação

Todas as operações de gerenciamento exigem os headers Authorization (token de acesso) e X-Tenant (ver Autenticação):

Operação	Endpoint
Criar	Criar webhook
Listar todos	Listar webhooks
Obter por ID	Obter webhook por ID
Atualizar	Atualizar webhook
Remover	Remover webhook
Listar por evento	Listar webhooks por evento

Eventos disponíveis

São 11 eventos que podem ser assinados. Depois de registrar o webhook (acima), siga o guia do evento para saber qual payload chega e como processá-lo:

Evento	Quando dispara	Guia
JOB_TALENT_ADDED	Um talento é inscrito em uma vaga (vira candidato)	Talento inscrito em uma vaga
JOB_TALENT_STAGE_ADDED	Um candidato muda de etapa no processo	Talento mudou de etapa
JOB_TALENT_UPDATED	Algo muda em uma candidatura (currículo, análise, triagem…)	Candidatura atualizada
JOB_TALENT_FIT_UPDATED	A triagem por IA (v3) atualizou a nota do candidato na vaga	Fit da triagem atualizado
FORM_RESPONSE_ADDED	Uma resposta de formulário é registrada	Resposta de formulário registrada
JOB_ADDED	Uma vaga é criada	Vaga criada
JOB_UPDATED	Uma vaga é atualizada	Vaga atualizada
JOB_REMOVED	Uma vaga é removida	Vaga removida
JOB_PAGE_CREATED	Uma página de divulgação é criada	Página de divulgação criada
REQUISITION_CREATED	Uma requisição de vaga é criada	Requisição criada
REQUISITION_STATUS_UPDATED	O status de uma requisição muda	Status de requisição atualizado

O corpo enviado para a sua URL muda de acordo com o evento — veja o detalhe no guia de cada um.

Filtrando com rules

Por padrão, um webhook recebe todas as ocorrências do evento. Use rules (no momento da criação) para receber apenas as que interessam — por exemplo, somente quando o candidato entra em uma etapa específica.

Cada regra compara um campo do payload do evento com um valor:

{
  "rules": {
    "stageName": { "operator": "=", "value": "Teste Técnico" }
  }
}

Operadores disponíveis: =, !=, >, <, >=, <=, contains, notContains.

Com mais de uma regra, o evento só é entregue quando todas casam, independentemente da ordem em que foram declaradas.

dica

Use os campos que realmente existem no payload daquele evento — uma regra que aponta para um campo inexistente, null ou vazio ("") faz o evento não ser entregue, com qualquer operador, inclusive !=: { "status": { "operator": "!=", "value": "rejected" } } não entrega o evento quando status não vem no payload. Confira os campos no guia do evento correspondente.

Segurança

A autenticação da sua ponta é responsabilidade sua. O InHire envia os headers que você configurou no webhook em toda chamada — use isso para validar que a requisição veio do InHire:

• Orientamos a configuração de um header de segurança no webhook, ex.: {"Authorization": "Bearer <TOKEN_DO_WEBHOOK>"} ou {"X-Webhook-Secret": "..."}.
• No seu endpoint, rejeite qualquer requisição que não traga esse header com o valor esperado.
• Exponha sempre uma URL https.

aviso

As notificações não são assinadas com HMAC. A garantia de autenticidade pode ser disponibilizada por meio de um header de segurança que você configura. Trate esse header como uma credencial e rotacione-o via Atualizar webhook se necessário.

Próximos passos

Depois de registrar o webhook, siga o guia do evento que você quer ouvir:

• Talento mudou de etapa
• Talento inscrito em uma vaga
• Resposta de formulário registrada
• Vaga criada
• Vaga atualizada
• Vaga removida
• Página de divulgação criada
• Requisição criada
• Status de requisição atualizado