Notificações por Webhook

Receba notificações em tempo real quando afiliados forem criados ou desativados no seu programa e quando uma indicação no app for contada. Os webhooks permitem sincronizar o estado dos afiliados com seus próprios sistemas automaticamente, sem necessidade de polling.

Como Funciona

Quando um afiliado é criado ou removido da sua empresa, ou uma indicação no app é contada, a Insert Affiliate envia uma solicitação HTTP POST para a URL de webhook configurada, com detalhes sobre o evento. Isso acontece automaticamente em segundo plano e não atrasa a operação do afiliado.

Configurando Webhooks

Vá até Settings → aba Integrations
1. Role até a seção Webhook Notifications
Insira sua Webhook URL — esta deve usar HTTPS
Opcionalmente, insira um Bearer Token — este será enviado no cabeçalho Authorization para que seu servidor possa verificar que as solicitações são genuinamente da Insert Affiliate
Clique em Save Changes

Seção Webhook Notifications nas configurações do painel da Insert Affiliate

Clique para ver em tamanho real

Seu bearer token é criptografado em repouso e nunca é exibido por completo após ser salvo.

Eventos de Webhook

`affiliate.created`

Enviado quando um afiliado é adicionado à sua empresa. Isso inclui todos os métodos de criação: adicionar um afiliado manualmente pelo painel, aprovar uma solicitação de autocadastro ou aceitar uma solicitação de ingresso de um afiliado.

Payload:

{
  "event": "affiliate.created",
  "affiliate_id": "ia_45fee001",
  "email": "[email protected]",
  "deep_link": "https://myapp.link/ref/abc123",
  "occurred_at": "2026-03-18T12:00:00.000Z"
}

Campos:

Campo	Tipo	Descrição
`event`	string	Sempre `"affiliate.created"`
`affiliate_id`	string	Um identificador determinístico para o afiliado, derivado do e-mail dele. Formato: `ia_` seguido de 8 caracteres hexadecimais. Consistente em todos os eventos do mesmo afiliado.
`email`	string	O endereço de e-mail do afiliado
`deep_link`	string	A URL do deep link atribuído ao afiliado. Isso é incluído quando um deep link foi atribuído (ex.: durante a aprovação de autocadastro ou a aceitação de uma solicitação de ingresso). Pode ser uma string vazia se nenhum deep link tiver sido atribuído ainda.
`occurred_at`	string	Timestamp ISO 8601 de quando o evento ocorreu

`affiliate.deactivated`

Enviado quando um afiliado é removido da sua empresa.

Payload:

{
  "event": "affiliate.deactivated",
  "affiliate_id": "ia_45fee001",
  "email": "[email protected]",
  "deep_link": "https://myapp.link/ref/abc123",
  "occurred_at": "2026-03-18T14:30:00.000Z"
}

Campos:

Campo	Tipo	Descrição
`event`	string	Sempre `"affiliate.deactivated"`
`affiliate_id`	string	O mesmo identificador determinístico que foi enviado no evento `affiliate.created` deste afiliado. Use-o para corresponder os eventos de criação e desativação.
`email`	string	O endereço de e-mail do afiliado
`deep_link`	string	A URL do deep link que estava atribuída ao afiliado no momento da remoção. String vazia se nenhum deep link tiver sido atribuído.
`occurred_at`	string	Timestamp ISO 8601 de quando o evento ocorreu

`referral.created`

Enviado quando acontece algo que seu programa de indicações no app conta como indicação: uma compra nova, o evento que você escolheu ou uma instalação, conforme sua configuração. Só é enviado quando as indicações no app estão ativadas, para indicadores que entraram pelo seu app.

Payload:

{
  "event": "referral.created",
  "affiliate_id": "ia_45fee001",
  "email": "[email protected]",
  "deep_link": "https://myapp.link/ref/abc123",
  "short_code": "a1b2c3d4",
  "trigger": "purchase",
  "referral_count": 3,
  "reward_status": "not_automatic",
  "occurred_at": "2026-09-18T12:00:00.000Z"
}

Campos:

Campo	Tipo	Descrição
`event`	string	Sempre `"referral.created"`
`affiliate_id`	string	O mesmo identificador enviado em `affiliate.created` para este afiliado
`email`	string	O endereço de e-mail do indicador
`deep_link`	string	O link do indicador, ou o código curto para empresas só com código curto
`short_code`	string	O código curto do indicador
`trigger`	string	O que foi contado: `"purchase"`, `"event"` ou `"install"`
`referral_count`	number	O novo total acumulado do indicador. Recompense até esse número, assim você nunca recompensa duas vezes e o próximo envio compensa qualquer um que você tenha perdido.
`reward_status`	string	O que aconteceu com a recompensa automática quando a indicação foi registrada: `granted`, `not_automatic` (sem recompensa automática: recompense você mesmo se escolheu Eu mesmo recompenso), `waiting_for_account`, `waiting_for_codes` (esperando a Apple gerar os códigos de oferta, ou você enviar mais códigos promocionais do Google Play; tentamos de novo a cada hora), `failed` ou `capped` (acima do limite mensal, não recompense esta). Enviado uma vez: uma recompensa em espera concedida depois não gera um segundo webhook. Veja a lista completa.
`occurred_at`	string	Timestamp ISO 8601 de quando o evento ocorreu

Autenticação

Se você configurou um bearer token, toda solicitação de webhook inclui o cabeçalho:

Authorization: Bearer

Seu servidor deve verificar que este cabeçalho corresponde ao token que você configurou na Insert Affiliate, para garantir que as solicitações são legítimas.

Notas de Comportamento

Fire-and-forget — A entrega do webhook não bloqueia a operação do afiliado. Se seu endpoint estiver fora do ar ou retornar um erro, o afiliado ainda será criado ou removido normalmente.
Apenas HTTPS — As URLs de webhook devem usar HTTPS por segurança.
Timeout — As solicitações expiram após 10 segundos. Certifique-se de que seu endpoint responde com rapidez.
Sem novas tentativas — Webhooks que falham não são repetidos. Se a confiabilidade for crítica, considere registrar os eventos recebidos do seu lado e reconciliá-los periodicamente com o painel da Insert Affiliate.
IDs de afiliado consistentes — O affiliate_id é determinístico e baseado no e-mail do afiliado. O mesmo e-mail sempre produzirá o mesmo affiliate_id, então você pode corresponder de forma confiável os eventos created e deactivated.

Exemplos de Casos de Uso

Sincronize afiliados com seu CRM — Crie ou arquive contatos automaticamente quando afiliados ingressam ou saem
Dispare fluxos de onboarding — Inicie um fluxo interno de onboarding quando um novo afiliado é aprovado
Atualize seu próprio banco de dados — Mantenha seus registros de usuários em sincronia com as mudanças de status dos afiliados
Alertas no Slack ou por e-mail — Encaminhe eventos para um canal de notificação da sua equipe