Um Webhook é um endpoint HTTP usado para receber notificações de eventos. Quando um evento específico ocorre, o sistema envia ativamente uma requisição HTTP para uma URL predefinida (a URL do Webhook). Webhooks são comumente usados para notificar sistemas externos sobre alterações de estado ou resultados de tarefas assíncronas.
A documentação de Webhook inclui detalhes como o nome do Webhook, o método da requisição e o corpo da requisição. Isso facilita para os usuários entenderem que tipo de dados será enviado quando determinado evento ocorrer.
Privacidade da URL de Depuração
A URL de Depuraçãonão será incluída na documentação nem na exportação OpenAPI — ela é usada apenas para testes internos.
No arquivo OpenAPI exportado, os endpoints de Webhook são listados no campo webhooks, que é diferente do campo paths dos endpoints regulares.
Por que definir Webhooks separadamente na documentação?
De acordo com a especificação OpenAPI 3.1:
Endpoints regulares são definidos no campo paths
Endpoints de Webhook são definidos no campo webhooks
Essa separação clara garante que:
Endpoints regulares sejam chamados por clientes externos para executar ações ou recuperar dados
Webhooks sejam acionados pelo sistema para notificar serviços externos
No Apidog, Webhooks são tratados como um tipo de endpoint distinto para refletir com precisão essa diferença direcional e garantir a formatação correta nas exportações OpenAPI.Exemplo:
/orders é um endpoint regular usado por clientes
orderPaid é um Webhook acionado pelo sistema quando um pedido é pago com sucesso
Um Webhook é apenas um endpoint regular?
A URL de Depuração aparecerá na minha documentação da API?
