Eventos assinados reduzem polling, mas exigem resposta rápida, deduplicação e fila. Veja como operar automações de IA com confiabilidade.
Resposta direta
Os webhooks da OpenAI enviam POST para um endpoint controlado pela empresa quando eventos selecionados acontecem. O receptor deve verificar a assinatura com o segredo fornecido, responder rapidamente com status 2xx e mover processamento relevante para uma fila. Entregas sem confirmação podem ser repetidas por até 72 horas com backoff exponencial, portanto todo consumidor precisa ser idempotente e tolerar eventos duplicados.
Assinatura autentica a origem
Verifique o corpo bruto com o segredo no servidor antes de aceitar o evento; segredo exposto deve ser rotacionado.
Resposta rápida separa recebimento de processamento
Confirme o recebimento e coloque trabalho pesado em fila. Executar tudo antes do 2xx aumenta timeout e repetição.
Duplicação é comportamento esperado
Retries protegem contra falhas transitórias. Armazene o identificador do evento e torne cada efeito idempotente.
Observabilidade fecha o ciclo
Registre recebimento, verificação, deduplicação, processamento, resultado e eventual fila morta sem expor dados sensíveis.
Leitura Nexus
Use webhook como entrada confiável de um workflow, não como execução direta de ações irreversíveis sem validação e autorização.
Perguntas frequentes
É obrigatório verificar a assinatura?
Sim, para confirmar que o POST foi emitido pela OpenAI e não por terceiro.
Por que responder 2xx rapidamente?
Para confirmar recebimento antes do timeout e evitar retentativas desnecessárias.
O mesmo evento pode chegar mais de uma vez?
Sim. O consumidor deve deduplicar e executar efeitos de forma idempotente.
Guias essenciais para aprofundar a decisão
Esta análise editorial foi produzida pela Nexus a partir das fontes oficiais abaixo, consultadas em 31 de outubro de 2026. O texto é original e interpreta implicações práticas para empresas.
- OpenAI Developers — Webhooks: configuração, assinatura, resposta 2xx, retries e rotação do segredo.
- Standard Webhooks — specification: formato interoperável de assinatura referenciado pela documentação oficial.
Data informada pela fonte principal: documentação oficial consultada em 31 de outubro de 2026; análise técnica.