Webhooks

Assinaturas de saída para os eventos da plataforma, seu signing secret e as tentativas de entrega que produziram — o maior recurso. Veja o modelo Webhook, o modelo WebhookDelivery e Segurança de webhooks para validação da assinatura HMAC.

Comando	HTTP	Descrição
webhooks list	GET /webhooks	Lista assinaturas. Signing secrets nunca são retornados.
webhooks get	GET /webhooks/{id}	Busca um webhook.
webhooks create	POST /webhooks	Cria uma assinatura. A resposta carrega o signing_secret em texto claro exatamente uma vez.
webhooks upsert	PUT /webhooks	Cria ou atualiza, casado por id e depois external_id.
webhooks update	PATCH /webhooks/{id}	Atualiza no local.
webhooks delete	DELETE /webhooks/{id}	Soft-delete.
webhooks test	POST /webhooks/{id}/test	Envia um webhook.ping sintético pelo caminho real de assinatura e retry.
webhooks regenerate-secret	POST /webhooks/{id}/regenerate-secret	Rotaciona o signing secret — retornado uma vez.
webhooks deliveries list	GET /webhooks/{id}/deliveries	Tentativas de entrega de um webhook.
webhooks deliveries get	GET /webhooks/{id}/deliveries/{deliveryId}	Busca uma entrega, com headers e corpos de request/response.
webhooks deliveries replay	POST /webhooks/{id}/deliveries/{deliveryId}/replay	Reenvia uma entrega com uma assinatura nova.

Exemplos

# Listar assinaturas ativas de uma inbox
kobana inbox webhooks list \
  --params '{"status": "active", "inbox_id": "INBOX_ID"}' \
  --fields "id,label,url,subscribed_events"

# Buscar um
kobana inbox webhooks get --params '{"id": "WEBHOOK_ID"}'

# Criar — salve a resposta, o signing_secret só volta desta vez
kobana inbox webhooks create \
  --json '{"label": "Sync de pedidos", "url": "https://example.com/hooks/kobana", "subscribed_events": ["email.processed"]}' \
  --output webhook.json

# Criar ou atualizar, casado por external_id
kobana inbox webhooks upsert \
  --json '{"external_id": "order-sync", "url": "https://example.com/hooks/kobana", "subscribed_events": ["email.processed", "webhook.test"]}'

# Atualizar os eventos assinados
kobana inbox webhooks update \
  --params '{"id": "WEBHOOK_ID"}' \
  --json '{"subscribed_events": ["email.processed"]}'

# Soft-delete
kobana inbox webhooks delete --params '{"id": "WEBHOOK_ID"}' --dry-run

# Enviar um ping de teste
kobana inbox webhooks test --params '{"id": "WEBHOOK_ID"}'

# Rotacionar o signing secret — salve a resposta, ele não volta de novo
kobana inbox webhooks regenerate-secret --params '{"id": "WEBHOOK_ID"}' --output new-secret.json

# Listar tentativas de entrega
kobana inbox webhooks deliveries list \
  --params '{"id": "WEBHOOK_ID", "status": "failed"}' \
  --fields "id,status,attempt,response_status"

# Inspecionar uma entrega
kobana inbox webhooks deliveries get \
  --params '{"id": "WEBHOOK_ID", "deliveryId": "DELIVERY_ID"}'

# Reenviá-la
kobana inbox webhooks deliveries replay \
  --params '{"id": "WEBHOOK_ID", "deliveryId": "DELIVERY_ID"}'

Próximos passos

• System events — os eventos aos quais um webhook está assinado.
• Flags globais — vale usar --output em toda escrita aqui.