{"openapi":"3.0.0","info":{"title":"CazVid Webhooks Public API","version":"1.0.0","description":"Register and manage outbound webhook endpoints and inspect deliveries. See https://cazvid.com/api/webhooks/v1 for guides and examples."},"servers":[{"url":"https://aio-backend-prod.cazvid.app"}],"paths":{"/api/v3.0/webhooks/public/webhook-endpoints":{"post":{"operationId":"webhooksCreateEndpoint","summary":"Register a webhook endpoint.","description":"Authenticate with an x-api-key header or Authorization: Bearer <key> (scope webhooks:manage). The signing secret (whsec_...) is returned ONCE in this response - store it now; it cannot be retrieved again from the public API. The endpoint is created pending_verification and receives a webhook.verify challenge it must echo to become active.","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateWebhookEndpointDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpointWithSecretDto"}}}}},"tags":["Webhooks API V3.0"],"security":[{"apiKey":[]},{"bearer":[]}]},"get":{"operationId":"webhooksListEndpoints","summary":"List the organization's webhook endpoints.","description":"Authenticate with an x-api-key header or Authorization: Bearer <key> (scope webhooks:read). Secrets are never included.","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListWebhookEndpointsResponseDto"}}}}},"tags":["Webhooks API V3.0"],"security":[{"apiKey":[]},{"bearer":[]}]}},"/api/v3.0/webhooks/public/webhook-endpoints/{id}":{"get":{"operationId":"webhooksGetEndpoint","summary":"Get a webhook endpoint with delivery stats.","description":"Authenticate with an x-api-key header or Authorization: Bearer <key> (scope webhooks:read).","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpointDetailDto"}}}}},"tags":["Webhooks API V3.0"],"security":[{"apiKey":[]},{"bearer":[]}]},"patch":{"operationId":"webhooksUpdateEndpoint","summary":"Update a webhook endpoint.","description":"Authenticate with an x-api-key header or Authorization: Bearer <key> (scope webhooks:manage). Changing the url re-opens verification. status may be set to active (requires a verified endpoint) or disabled.","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateWebhookEndpointDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpointDto"}}}}},"tags":["Webhooks API V3.0"],"security":[{"apiKey":[]},{"bearer":[]}]},"delete":{"operationId":"webhooksDeleteEndpoint","summary":"Delete a webhook endpoint (soft delete).","description":"Authenticate with an x-api-key header or Authorization: Bearer <key> (scope webhooks:manage). Deletion stops all in-flight retries.","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookDeletedResultDto"}}}}},"tags":["Webhooks API V3.0"],"security":[{"apiKey":[]},{"bearer":[]}]}},"/api/v3.0/webhooks/public/webhook-endpoints/{id}/rotate-secret":{"post":{"operationId":"webhooksRotateSecret","summary":"Rotate a webhook endpoint's signing secret.","description":"Authenticate with an x-api-key header or Authorization: Bearer <key> (scope webhooks:manage). Returns the NEW secret once; the previous secret keeps signing in parallel for 24 hours so consumers can roll over.","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookSecretDto"}}}}},"tags":["Webhooks API V3.0"],"security":[{"apiKey":[]},{"bearer":[]}]}},"/api/v3.0/webhooks/public/webhook-endpoints/{id}/verify":{"post":{"operationId":"webhooksVerifyEndpoint","summary":"(Re)send the ownership verification challenge.","description":"Authenticate with an x-api-key header or Authorization: Bearer <key> (scope webhooks:manage). Sends a webhook.verify event; the endpoint must echo the challenge in its 2xx body to become active. Limited to 5/hour.","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookVerifyResultDto"}}}}},"tags":["Webhooks API V3.0"],"security":[{"apiKey":[]},{"bearer":[]}]}},"/api/v3.0/webhooks/public/webhook-endpoints/{id}/test":{"post":{"operationId":"webhooksTestEndpoint","summary":"Send a test ping to a webhook endpoint.","description":"Authenticate with an x-api-key header or Authorization: Bearer <key> (scope webhooks:manage). Enqueues a webhook.ping event. Limited to 10/day per endpoint; pings never affect suspension state.","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookTestResultDto"}}}}},"tags":["Webhooks API V3.0"],"security":[{"apiKey":[]},{"bearer":[]}]}},"/api/v3.0/webhooks/public/webhook-endpoints/{id}/deliveries":{"get":{"operationId":"webhooksListDeliveries","summary":"List an endpoint's delivery log (metadata only).","description":"Authenticate with an x-api-key header or Authorization: Bearer <key> (scope webhooks:read). Returns delivery METADATA only - event payloads are never returned. Paginate with `before` (a delivery id) and `limit`.","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}},{"name":"limit","required":true,"in":"query","schema":{"type":"string"}},{"name":"before","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookDeliveriesResponseDto"}}}}},"tags":["Webhooks API V3.0"],"security":[{"apiKey":[]},{"bearer":[]}]}},"/api/v3.0/webhooks/public/webhook-endpoints/{id}/deliveries/{deliveryId}/redeliver":{"post":{"operationId":"webhooksRedeliver","summary":"Re-queue a stored delivery for another attempt.","description":"Authenticate with an x-api-key header or Authorization: Bearer <key> (scope webhooks:manage). Re-queues the stored event (30-day window) with a fresh attempt counter; does not touch the endpoint's suspension state.","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}},{"name":"deliveryId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookRedeliverResultDto"}}}}},"tags":["Webhooks API V3.0"],"security":[{"apiKey":[]},{"bearer":[]}]}},"/api/v3.0/webhooks/public/events":{"get":{"operationId":"webhookslistEvents","summary":"List the subscribable webhook event catalog.","description":"Authenticate with an x-api-key header or Authorization: Bearer <key> (scope webhooks:read). Throttled to 60 requests per minute per API key.","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEventsResponseDto"}}}}},"tags":["Webhooks API V3.0"],"security":[{"apiKey":[]},{"bearer":[]}]}},"/api/v3.0/webhooks/public/usage":{"get":{"operationId":"webhooksUsage","summary":"Endpoint count and delivery usage for the calling organization.","description":"Authenticate with an x-api-key header or Authorization: Bearer <key> (scope webhooks:read). Does not consume the delivery cap. Throttled to 60 requests per minute per API key.","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookUsageDto"}}}}},"tags":["Webhooks API V3.0"],"security":[{"apiKey":[]},{"bearer":[]}]}},"/api/v3.0/webhooks/public/assets/{token}":{"get":{"operationId":"webhooksRedeemAsset","summary":"Redeem an asset token to a fresh presigned download URL.","description":"Authenticate with an x-api-key header or Authorization: Bearer <key> (scope webhooks:read). Redeems an asset token from a delivered application.received payload and 302-redirects to a fresh, short-lived presigned download URL. The token's organization must match the authenticated key's organization.","parameters":[{"name":"token","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"302":{"description":"Redirect (302) to a fresh, short-lived presigned download URL."}},"tags":["Webhooks API V3.0"],"security":[{"apiKey":[]},{"bearer":[]}]}}},"components":{"schemas":{"CreateWebhookEndpointDto":{"type":"object","properties":{"url":{"type":"string","description":"HTTPS endpoint URL that will receive signed event POSTs.","example":"https://example.com/hooks/cazvid"},"events":{"type":"array","description":"Event types to subscribe to (deny-by-default).","example":["application.received"],"items":{"type":"string","enum":["application.received"]}},"description":{"type":"string","nullable":true,"maxLength":300},"workspaceIds":{"description":"Restrict deliveries to these workspace ids (empty/omitted = org-wide). Must be a subset of the API key's workspaces.","type":"array","items":{"type":"array"}}},"required":["url","events"]},"WebhookEndpointWithSecretDto":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"description":{"type":"string","nullable":true},"events":{"type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["pending_verification","active","disabled","suspended"]},"workspaceIds":{"type":"array","items":{"type":"string"}},"apiVersion":{"type":"string"},"verifiedAt":{"type":"string","nullable":true},"failingSince":{"type":"string","nullable":true},"suspendedAt":{"type":"string","nullable":true},"suspendReason":{"type":"string","nullable":true},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"secret":{"type":"string","description":"The signing secret (whsec_...). Returned ONCE at create/rotate - store it now; it cannot be retrieved again from the public API."}},"required":["id","url","description","events","status","workspaceIds","apiVersion","verifiedAt","failingSince","suspendedAt","suspendReason","createdAt","updatedAt","secret"]},"ListWebhookEndpointsResponseDto":{"type":"object","properties":{"endpoints":{"type":"array","items":{"$ref":"#/components/schemas/WebhookEndpointDto"}}},"required":["endpoints"]},"WebhookEndpointDetailDto":{"type":"object","properties":{"endpoint":{"$ref":"#/components/schemas/WebhookEndpointDto"},"stats":{"$ref":"#/components/schemas/WebhookEndpointStatsDto"}},"required":["endpoint","stats"]},"UpdateWebhookEndpointDto":{"type":"object","properties":{"url":{"type":"string","maxLength":2048},"events":{"type":"array","items":{"type":"string","enum":["application.received"]}},"description":{"type":"string","nullable":true,"maxLength":300},"status":{"type":"string","enum":["active","disabled"],"description":"Enable or disable the endpoint. Enabling requires a verified endpoint."}}},"WebhookEndpointDto":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"description":{"type":"string","nullable":true},"events":{"type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["pending_verification","active","disabled","suspended"]},"workspaceIds":{"type":"array","items":{"type":"string"}},"apiVersion":{"type":"string"},"verifiedAt":{"type":"string","nullable":true},"failingSince":{"type":"string","nullable":true},"suspendedAt":{"type":"string","nullable":true},"suspendReason":{"type":"string","nullable":true},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","url","description","events","status","workspaceIds","apiVersion","verifiedAt","failingSince","suspendedAt","suspendReason","createdAt","updatedAt"]},"WebhookDeletedResultDto":{"type":"object","properties":{"deleted":{"type":"boolean"}},"required":["deleted"]},"WebhookSecretDto":{"type":"object","properties":{"secret":{"type":"string","description":"The signing secret (whsec_...)."}},"required":["secret"]},"WebhookVerifyResultDto":{"type":"object","properties":{"verified":{"type":"boolean"},"statusCode":{"type":"number","nullable":true},"error":{"type":"string","nullable":true}},"required":["verified","statusCode","error"]},"WebhookTestResultDto":{"type":"object","properties":{"queued":{"type":"boolean"},"deliveryId":{"type":"string"}},"required":["queued","deliveryId"]},"WebhookDeliveriesResponseDto":{"type":"object","properties":{"deliveries":{"type":"array","items":{"$ref":"#/components/schemas/WebhookDeliveryDto"}},"hasMore":{"type":"boolean"}},"required":["deliveries","hasMore"]},"WebhookRedeliverResultDto":{"type":"object","properties":{"queued":{"type":"boolean"}},"required":["queued"]},"WebhookEventsResponseDto":{"type":"object","properties":{"events":{"type":"array","items":{"$ref":"#/components/schemas/WebhookEventCatalogItemDto"}}},"required":["events"]},"WebhookUsageDto":{"type":"object","properties":{"endpointCount":{"type":"number"},"deliveriesToday":{"type":"number"},"dailyCap":{"type":"number"},"resetsAt":{"type":"string"}},"required":["endpointCount","deliveriesToday","dailyCap","resetsAt"]},"WebhookEndpointStatsDto":{"type":"object","properties":{"delivered":{"type":"number"},"failed":{"type":"number"},"pending":{"type":"number"},"sending":{"type":"number"},"total":{"type":"number"}},"required":["delivered","failed","pending","sending","total"]},"WebhookDeliveryDto":{"type":"object","properties":{"id":{"type":"string"},"eventId":{"type":"string"},"type":{"type":"string"},"status":{"type":"string","enum":["pending","sending","delivered","failed"]},"attemptCount":{"type":"number"},"responseStatus":{"type":"number","nullable":true},"lastError":{"type":"string","nullable":true},"nextAttemptAt":{"type":"string","nullable":true},"deliveredAt":{"type":"string","nullable":true},"occurredAt":{"type":"string","nullable":true},"createdAt":{"type":"string"}},"required":["id","eventId","type","status","attemptCount","responseStatus","lastError","nextAttemptAt","deliveredAt","occurredAt","createdAt"]},"WebhookEventCatalogItemDto":{"type":"object","properties":{"type":{"type":"string"},"description":{"type":"string"},"subscribable":{"type":"boolean"}},"required":["type","description","subscribable"]}},"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"x-api-key"},"bearer":{"type":"http","scheme":"bearer"}}}}