> For the complete documentation index, see [llms.txt](https://tsanet.gitbook.io/connect/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://tsanet.gitbook.io/connect/api-reference/webhooks-v2.md).

# Webhooks V2

V2 webhook subscriptions (CloudEvents 1.0 — all 5 event types)

## GET /v2/webhooks

> List V2 webhook subscriptions for the current company

```json
{"openapi":"3.0.1","info":{"title":"OpenAPI definition","version":"v0"},"tags":[{"name":"WebhooksV2","description":"V2 webhook subscriptions (CloudEvents 1.0 — all 5 event types)"}],"servers":[{"url":"http://connect2.tsanet.org","description":"Generated server url"}],"security":[{"bearerAuth":[]}],"paths":{"/v2/webhooks":{"get":{"tags":["WebhooksV2"],"summary":"List V2 webhook subscriptions for the current company","operationId":"listWebhookSubscriptionsV2","responses":{"200":{"description":"List of V2 webhook subscriptions","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/WebhookSubscriptionV2DTO"}}},"application/problem+json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/WebhookSubscriptionV2DTO"}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"schemas":{"WebhookSubscriptionV2DTO":{"type":"object","properties":{"id":{"type":"integer","format":"int64"},"callbackUrl":{"type":"string"},"eventTypes":{"type":"array","items":{"type":"string","enum":["org.tsanet.connect.collaboration-request.created","org.tsanet.connect.collaboration-request.closed","org.tsanet.connect.collaboration-request.note.created","org.tsanet.connect.collaboration-request.response.created","org.tsanet.connect.collaboration-request.response.updated"]}},"active":{"type":"boolean"},"callbackAuthType":{"type":"string","description":"The authentication type configured for this subscription. Credential values are never returned."},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"ErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"validationErrors":{"type":"array","items":{"$ref":"#/components/schemas/ValidationError"}}}},"ValidationError":{"type":"object","properties":{"field":{"type":"string"},"message":{"type":"string"}}}}}}
```

## Register a new V2 webhook subscription (CloudEvents)

> Subscribe to receive CloudEvents 1.0 structured webhook notifications. Connect 2 will POST  event types to your callback URL.  Use \`eventTypes\` to filter which events you receive. Event type strings must match the CloudEvent \`type\` field exactly as it appears in delivered payloads (e.g. \`org.tsanet.connect.collaboration-request.created\`).  \*\*Security\*\*: Every delivery is signed with HMAC-SHA256. The signature is sent in the \`X-Hub-Signature-256\` header as \`sha256=\<hex>\`. Verify it using the secret returned on subscription creation (rotate via \`POST /v1/webhooks/{id}/secret\`).  \*\*Retries\*\*: Failed deliveries are retried up to 4 additional times (5 total attempts) with exponential backoff starting at 10s, doubling each attempt, capped at 300s. Messages that exhaust all retries are moved to a dead-letter queue. Contact TSANet support to replay dead-lettered deliveries.&#x20;

```json
{"openapi":"3.0.1","info":{"title":"OpenAPI definition","version":"v0"},"tags":[{"name":"WebhooksV2","description":"V2 webhook subscriptions (CloudEvents 1.0 — all 5 event types)"}],"servers":[{"url":"http://connect2.tsanet.org","description":"Generated server url"}],"security":[{"bearerAuth":[]}],"paths":{"/v2/webhooks":{"post":{"tags":["WebhooksV2"],"summary":"Register a new V2 webhook subscription (CloudEvents)","description":"Subscribe to receive CloudEvents 1.0 structured webhook notifications. Connect 2 will POST  event types to your callback URL.  Use `eventTypes` to filter which events you receive. Event type strings must match the CloudEvent `type` field exactly as it appears in delivered payloads (e.g. `org.tsanet.connect.collaboration-request.created`).  **Security**: Every delivery is signed with HMAC-SHA256. The signature is sent in the `X-Hub-Signature-256` header as `sha256=<hex>`. Verify it using the secret returned on subscription creation (rotate via `POST /v1/webhooks/{id}/secret`).  **Retries**: Failed deliveries are retried up to 4 additional times (5 total attempts) with exponential backoff starting at 10s, doubling each attempt, capped at 300s. Messages that exhaust all retries are moved to a dead-letter queue. Contact TSANet support to replay dead-lettered deliveries. ","operationId":"createWebhookSubscriptionV2","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateWebhookSubscriptionV2RequestDTO"}}},"required":true},"responses":{"200":{"description":"Webhook subscription created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookSubscriptionV2ResponseDTO"}},"application/problem+json":{"schema":{"$ref":"#/components/schemas/WebhookSubscriptionV2ResponseDTO"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"schemas":{"CreateWebhookSubscriptionV2RequestDTO":{"required":["callbackUrl"],"type":"object","properties":{"callbackUrl":{"type":"string","description":"The URL to receive webhook events. Must be accessible via HTTPS in production.","format":"uri"},"eventTypes":{"type":"array","description":"Optional list of CloudEvent type strings to subscribe to. If empty or null, all 5 event types are delivered. Values must match `WebhookEventTypeV2` exactly. ","items":{"type":"string","description":"Optional list of CloudEvent type strings to subscribe to. If empty or null, all 5 event types are delivered. Values must match `WebhookEventTypeV2` exactly. ","enum":["org.tsanet.connect.collaboration-request.created","org.tsanet.connect.collaboration-request.closed","org.tsanet.connect.collaboration-request.note.created","org.tsanet.connect.collaboration-request.response.created","org.tsanet.connect.collaboration-request.response.updated"]}},"callbackAuth":{"$ref":"#/components/schemas/WebhookCallbackAuthDTO"}}},"WebhookCallbackAuthDTO":{"required":["type"],"type":"object","properties":{"type":{"type":"string","enum":["NONE","BASIC","BEARER","HEADER"]},"username":{"type":"string","description":"Required when type is BASIC."},"password":{"type":"string","description":"Required when type is BASIC."},"token":{"type":"string","description":"Required when type is BEARER."},"headerName":{"type":"string","description":"Required when type is HEADER. The name of the custom header to send."},"headerValue":{"type":"string","description":"Required when type is HEADER. The value of the custom header to send."}}},"WebhookSubscriptionV2ResponseDTO":{"type":"object","properties":{"id":{"type":"integer","format":"int64"},"callbackUrl":{"type":"string"},"eventTypes":{"type":"array","items":{"type":"string","enum":["org.tsanet.connect.collaboration-request.created","org.tsanet.connect.collaboration-request.closed","org.tsanet.connect.collaboration-request.note.created","org.tsanet.connect.collaboration-request.response.created","org.tsanet.connect.collaboration-request.response.updated"]}},"active":{"type":"boolean"},"secret":{"type":"string","description":"HMAC secret for signing webhooks (only returned on creation — use POST /v1/webhooks/{id}/secret to rotate)"},"callbackAuthType":{"type":"string","description":"The authentication type configured for this subscription. Credential values are never returned."},"createdAt":{"type":"string","format":"date-time"}}},"ErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"validationErrors":{"type":"array","items":{"$ref":"#/components/schemas/ValidationError"}}}},"ValidationError":{"type":"object","properties":{"field":{"type":"string"},"message":{"type":"string"}}}}}}
```