Webhooks

Suscripciones salientes a los eventos de la plataforma, su signing secret y los intentos de entrega que produjeron — el recurso más grande. Ver el modelo Webhook, el modelo WebhookDelivery y Seguridad de webhooks para la validación de la firma HMAC.

Comando	HTTP	Descripción
webhooks list	GET /webhooks	Lista suscripciones. Los signing secrets nunca se devuelven.
webhooks get	GET /webhooks/{id}	Obtiene un webhook.
webhooks create	POST /webhooks	Crea una suscripción. La respuesta lleva el signing_secret en texto claro exactamente una vez.
webhooks upsert	PUT /webhooks	Crea o actualiza, emparejado por id y luego external_id.
webhooks update	PATCH /webhooks/{id}	Actualiza en el lugar.
webhooks delete	DELETE /webhooks/{id}	Soft-delete.
webhooks test	POST /webhooks/{id}/test	Envía un webhook.ping sintético por el camino real de firma y reintento.
webhooks regenerate-secret	POST /webhooks/{id}/regenerate-secret	Rota el signing secret — se devuelve una vez.
webhooks deliveries list	GET /webhooks/{id}/deliveries	Intentos de entrega de un webhook.
webhooks deliveries get	GET /webhooks/{id}/deliveries/{deliveryId}	Obtiene una entrega, con headers y cuerpos de request/response.
webhooks deliveries replay	POST /webhooks/{id}/deliveries/{deliveryId}/replay	Reenvía una entrega con una firma nueva.

Ejemplos

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

# Obtener uno
kobana inbox webhooks get --params '{"id": "WEBHOOK_ID"}'

# Crear — guarda la respuesta, el signing_secret solo vuelve esta vez
kobana inbox webhooks create \
  --json '{"label": "Sincronización de pedidos", "url": "https://example.com/hooks/kobana", "subscribed_events": ["email.processed"]}' \
  --output webhook.json

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

# Actualizar los eventos suscritos
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 un ping de prueba
kobana inbox webhooks test --params '{"id": "WEBHOOK_ID"}'

# Rotar el signing secret — guarda la respuesta, no vuelve de nuevo
kobana inbox webhooks regenerate-secret --params '{"id": "WEBHOOK_ID"}' --output new-secret.json

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

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

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

Próximos pasos

• System events — los eventos a los que está suscrito un webhook.
• Flags globales — vale la pena usar --output en cada escritura aquí.