Webhook de afiliados

Um webhook de afiliados é uma notificação HTTP enviada a outro sistema quando ocorre um evento relacionado a afiliados, como uma conversão, atualização de comissão ou mudança no status do pagamento. Um callback ou postback pode ser usado em integrações relacionadas. Os gatilhos e as cargas úteis compatíveis dependem da plataforma.

Terminologia de webhook, callback e postback

Esses nomes se sobrepõem entre plataformas. Webhook descreve uma notificação HTTP acionada por um evento. Callback é um termo mais amplo para uma resposta ou notificação enviada a outro sistema. Em integrações de afiliados, postback geralmente se refere a um evento de conversão enviado pelo servidor. A direção, por si só, não estabelece uma distinção universal.

Exemplos de eventos e ações do sistema receptor

Estes são exemplos conceituais, não uma garantia de que todas as plataformas disponibilizem esses gatilhos. Confirme o catálogo de eventos e a versão da carga útil antes de projetar o sistema receptor.

Webhooks versus consulta periódica

A consulta periódica solicita alterações a uma API em intervalos definidos. Os webhooks enviam os eventos compatíveis conforme eles ocorrem. Webhooks podem reduzir consultas repetidas à API, enquanto a consulta periódica ou a reconciliação pode ajudar a recuperar estados ausentes. Uma integração robusta pode usar ambos, em vez de presumir que as notificações são completas e chegam em ordem.

Exemplo de notificação duplicada

Um evento de aprovação é entregue duas vezes após um tempo limite. O sistema receptor reconhece o mesmo ID de evento e registra uma única transição de estado. Um reembolso posterior é um evento diferente que ainda precisa ser processado, embora se refira à mesma transação.

Por isso, deduplicar todos os webhooks somente pelo ID da transação pode ser incorreto. A identidade do evento e a identidade da transação têm funções diferentes.

Verificações operacionais

Mantenha as credenciais fora de exemplos públicos, registre os resultados das entregas sem dados desnecessários dos clientes e configure alertas para falhas repetidas. O sistema receptor deve confirmar o recebimento das solicitações conforme o protocolo documentado pelo remetente e processar os efeitos financeiros com segurança. Reconcilie estados importantes com a plataforma de referência, em vez de confiar apenas no horário de chegada das notificações.

Como projetar um sistema receptor para condições reais de entrega

Confirme qual evento inicia a notificação e se ele se refere a uma comissão registrada, aprovada ou paga. Armazene o identificador do evento e o identificador da entidade relevante, valide a solicitação usando o mecanismo de autenticação compatível do remetente e coloque em uma fila os trabalhos que não puderem ser concluídos rapidamente.

Planeje-se para eventos duplicados, atrasados, com falha e fora de ordem. Uma nova tentativa deve atualizar o mesmo registro, em vez de pagar um bônus duas vezes. Se uma aprovação chegar antes do registro local da venda, recupere ou reconcilie o estado ausente, em vez de tratar a ordem de chegada como uma regra de negócio.

A documentação oficial de webhooks da Stripe descreve padrões de entrega e projeto de endpoints; as assinaturas e cargas úteis são específicas da Stripe. Consulte a documentação da própria plataforma de afiliados para conhecer os campos reais, os gatilhos compatíveis e a autenticação. Teste respostas com falha e reconciliação antes de conectar um webhook a uma ação financeira.

Para as configurações correspondentes do Post Affiliate Pro, consulte a documentação de callbacks de webhooks . Confirme a configuração e os requisitos de integração de acordo com as regras do seu programa.

Etapas resumidas