Webhooks
Assinaturas de eventos, entregas e reenvio.
Listar tipos de evento de webhook
Lista os tipos de evento da organização que podem ser assinados por webhook, com descrição e tipo de recurso. Requer a permissão `identity.webhooks.read`.
Criar webhook
Cadastra um endpoint com `name`, `url` (HTTPS público; inválida ou insegura retorna `400`) e `event_kinds` (1 a 20 tipos válidos). O segredo de assinatura é devolvido uma única vez nesta resposta. Requer a permissão `identity.webhooks.manage`. A organização pode ter até 25 webhooks ativos.
Listar webhooks
Lista os webhooks da organização. Requer a permissão `identity.webhooks.read`. Listagem paginada no envelope `{items, page}` com `limit`/`cursor` (também aceita `sort`, `q` e `filter`).
Consultar webhook
Retorna o webhook com URL, eventos assinados, prefixo do segredo, estado de pausa e se inclui casos protegidos; o segredo nunca é devolvido. Requer a permissão `identity.webhooks.read`. O `webhook_id` é o código público de 4 caracteres; inexistente retorna `404`.
Atualizar webhook
Altera `name`, `url`, `event_kinds` e/ou `include_protected` (se o endpoint também é avisado sobre casos protegidos, sem nenhum conteúdo deles; a mudança é auditada). Requer a permissão `identity.webhooks.manage`. O `webhook_id` é o código público de 4 caracteres do webhook; webhook inexistente ou revogado retorna `404`.
Pausar webhook
Para de enfileirar entregas para este endpoint; o que acontecer durante a pausa não é entregue depois. Pausar um webhook já pausado não muda nada. Requer a permissão `identity.webhooks.manage`. O `webhook_id` é o código público de 4 caracteres do webhook; webhook inexistente ou revogado retorna `404`.
Retomar webhook
Retoma o envio de entregas e zera a contagem de falhas; eventos ocorridos durante a pausa não são enviados. Requer a permissão `identity.webhooks.manage`. O `webhook_id` é o código público de 4 caracteres do webhook; webhook inexistente ou revogado retorna `404`.
Rotacionar segredo do webhook
Gera um novo segredo, exibido uma única vez. Por 24 horas as entregas são assinadas com o novo e o anterior, para o receptor trocar o segredo sem perder entregas. Requer a permissão `identity.webhooks.manage`. O `webhook_id` é o código público de 4 caracteres do webhook; webhook inexistente ou revogado retorna `404`.
Testar webhook
Enfileira uma entrega `webhook.ping` (uma tentativa) e responde `202` com o `delivery_id`; o resultado aparece nas entregas. Requer a permissão `identity.webhooks.manage`. Limite de 20 testes por hora por webhook (`429`). O `webhook_id` é o código público de 4 caracteres do webhook; webhook inexistente ou revogado retorna `404`.
Consultar entrega de webhook
Retorna uma entrega com status, tentativa, código HTTP recebido, duração e o corpo enviado; a resposta do receptor nunca é armazenada. Requer a permissão `identity.webhooks.read`. O `delivery_id` é UUID; entrega inexistente retorna `404`.
Reenviar entrega de webhook
Tenta mais uma vez uma entrega com falha ou esgotada (mesmo id de evento no corpo) e responde `202`. Entrega em outro estado retorna `409` `webhook_delivery_state`. Requer a permissão `identity.webhooks.manage`. Limite de 120 reenvios por hora por webhook (`429`).
Revogar webhook
Revoga o webhook de forma definitiva: ele deixa de receber entregas e não pode mais ser alterado. Responde `204`. Requer a permissão `identity.webhooks.manage`. O `webhook_id` é o código público de 4 caracteres do webhook; webhook inexistente ou revogado retorna `404`.
Listar entregas do webhook
Lista as entregas do webhook (eventos, testes e reenvios). Requer a permissão `identity.webhooks.read`. O `webhook_id` é o código público; inexistente retorna `404`. Listagem paginada no envelope `{items, page}` com `limit`/`cursor` (também aceita `sort`, `q` e `filter`).