> 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-v1.md).
# Webhooks V1
V1 webhook subscriptions (legacy flat JSON — collaboration-request.created and note.created only)
## List webhook subscriptions for the current company
> \*\*Deprecated\*\* — use \`GET /v2/webhooks\` instead.\
> This endpoint will be removed after 2027-01-01.
```json
{"openapi":"3.0.3","info":{"title":"TSANet Connect Core API","version":"1.0.0"},"tags":[{"name":"WebhooksV1","description":"V1 webhook subscriptions (legacy flat JSON — collaboration-request.created and note.created only)"}],"servers":[{"url":"http://localhost:8080","description":"Local"},{"url":"https://connect2.tahoelab.us","description":"Dev"},{"url":"https://connect2.tsanet.net","description":"Beta"},{"url":"https://connect2.tsanet.org","description":"Prod"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Paste a Bearer JWT here. Two token types are accepted:\n\n**Connect1 User Tokens** — issued by the Connect1 identity service. Copy the token from your Connect1 session.\n\n**Azure AD M2M** — use the `azureClientCredentials` scheme below to get a token, then paste it here.\n"}},"schemas":{"WebhookSubscriptionDTO":{"type":"object","properties":{"id":{"type":"integer","format":"int64"},"callbackUrl":{"type":"string","maxLength":500},"eventTypes":{"type":"array","items":{"$ref":"#/components/schemas/WebhookEventType"}},"caseDirections":{"type":"array","items":{"$ref":"#/components/schemas/WebhookCaseDirection"}},"partnerCompanyIds":{"type":"array","items":{"type":"integer","format":"int64"}},"payloadVersion":{"$ref":"#/components/schemas/WebhookPayloadVersion"},"active":{"type":"boolean"},"callbackAuthType":{"$ref":"#/components/schemas/WebhookCallbackAuthType","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"}}},"WebhookEventType":{"type":"string","enum":["collaboration-request.created","note.created"],"description":"V1 webhook event type short names. Only `collaboration-request.created` and `note.created`\nare delivered via V1 subscriptions. For the full set of 5 event types, use\n`POST /v2/webhooks` with `WebhookEventTypeV2` strings.\n"},"WebhookCaseDirection":{"type":"string","enum":["INBOUND","OUTBOUND"],"description":"Direction relative to the company that owns the webhook subscription.\nINBOUND means the subscribed company receives the case; OUTBOUND means it submits the case.\n"},"WebhookPayloadVersion":{"type":"string","enum":["V1","V2"],"default":"V1","description":"Payload format version for webhook deliveries. See the Connect Webhook Events\nAsyncAPI specification for full payload and header details per version.\n- **V1** (default): Legacy flat JSON. Only `collaboration-request.created` and `note.created` are delivered.\n- **V2**: CloudEvents 1.0 structured binding. All 5 event types are delivered.\n"},"WebhookCallbackAuthType":{"type":"string","enum":["NONE","BASIC","BEARER","HEADER","OAUTH2_CLIENT_CREDENTIALS"],"description":"Authentication type TSANet uses when delivering webhook events. Credentials are sent in\naddition to the X-Hub-Signature-256 HMAC header.\n\n- **NONE**: No callback authentication header.\n- **BASIC**: `Authorization: Basic `.\n- **BEARER**: `Authorization: Bearer ` using a static token.\n- **HEADER**: Sends the configured name and value as a custom header.\n- **OAUTH2_CLIENT_CREDENTIALS**: Obtains a short-lived access token from the configured\n OAuth2 token endpoint before delivery, then sends `Authorization: Bearer `.\n"},"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"}}},"ProblemDetail":{"type":"object","properties":{"type":{"type":"string","format":"uri"},"title":{"type":"string"},"status":{"type":"integer","format":"int32"},"detail":{"type":"string"},"instance":{"type":"string","format":"uri"}},"additionalProperties":true}}},"paths":{"/v1/webhooks":{"get":{"tags":["WebhooksV1"],"summary":"List webhook subscriptions for the current company","deprecated":true,"description":"**Deprecated** — use `GET /v2/webhooks` instead.\nThis endpoint will be removed after 2027-01-01.\n","operationId":"listWebhookSubscriptions","responses":{"200":{"description":"List of webhook subscriptions","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/WebhookSubscriptionDTO"}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}}}}}
```
## Register a new V1 webhook subscription (legacy flat JSON)
> \*\*Deprecated\*\* — use \`POST /v2/webhooks\` instead.\
> This endpoint will be removed after 2027-01-01.\
> \
> Subscribe to receive legacy flat JSON webhook notifications for\
> \`collaboration-request.created\` and \`note.created\` events.\
> \
> For new integrations, prefer \`POST /v2/webhooks\` which delivers all 5 event types\
> as CloudEvents 1.0 structured payloads.\
> \
> \*\*Security\*\*: Every delivery is signed with HMAC-SHA256. The signature is sent in the\
> \`X-Hub-Signature-256\` header as \`sha256=\\`. Verify it using the secret returned\
> on subscription creation. The secret cannot be rotated: to change it, delete the\
> subscription and create a new one.\
> \
> \*\*Retries\*\*: A \`2xx\` response counts as delivered. A \`4xx\` response is a permanent\
> failure and is not retried. Any other response (for example \`5xx\`), a connection error,\
> or no response within 30 seconds is retried: each delivery gets up to 3 attempts in\
> total (the first attempt plus 2 retries), 1 hour apart. After the third failed attempt\
> the delivery is moved to a dead-letter queue and is not attempted again automatically.\
> Every attempt is recorded as its own row in \`GET /v1/webhooks/{id}/deliveries\`.\
> Contact TSANet support about dead-lettered deliveries.
```json
{"openapi":"3.0.3","info":{"title":"TSANet Connect Core API","version":"1.0.0"},"tags":[{"name":"WebhooksV1","description":"V1 webhook subscriptions (legacy flat JSON — collaboration-request.created and note.created only)"}],"servers":[{"url":"http://localhost:8080","description":"Local"},{"url":"https://connect2.tahoelab.us","description":"Dev"},{"url":"https://connect2.tsanet.net","description":"Beta"},{"url":"https://connect2.tsanet.org","description":"Prod"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Paste a Bearer JWT here. Two token types are accepted:\n\n**Connect1 User Tokens** — issued by the Connect1 identity service. Copy the token from your Connect1 session.\n\n**Azure AD M2M** — use the `azureClientCredentials` scheme below to get a token, then paste it here.\n"}},"schemas":{"CreateWebhookSubscriptionRequestDTO":{"type":"object","required":["callbackUrl"],"properties":{"callbackUrl":{"type":"string","format":"uri","description":"The URL to receive webhook events. Must be accessible via HTTPS in production."},"eventTypes":{"type":"array","items":{"$ref":"#/components/schemas/WebhookEventType"},"description":"Optional list of V1 event types to subscribe to. If empty or null, both\n`collaboration-request.created` and `note.created` are delivered.\n"},"caseDirections":{"type":"array","items":{"$ref":"#/components/schemas/WebhookCaseDirection"},"minItems":1,"description":"Optional case directions relative to the subscribed company. If omitted or null,\nboth inbound and outbound cases are delivered.\n"},"partnerCompanyIds":{"type":"array","items":{"type":"integer","format":"int64"},"description":"Optional IDs of partner companies to include. If omitted or empty, cases involving\nany partner company are delivered.\n"},"callbackAuth":{"$ref":"#/components/schemas/WebhookCallbackAuthDTO","description":"Optional credential TSANet will attach to every delivery POST, in addition to the\nexisting HMAC-SHA256 signature. If omitted, deliveries are unauthenticated (current\nbehaviour). For OAUTH2_CLIENT_CREDENTIALS, TSANet obtains an OAuth2 access token\nusing the supplied token endpoint and client credentials, optionally requesting the\nconfigured scope, then sends it as\n`Authorization: Bearer `. Requires callbackUrl to be HTTPS when type is not NONE.\n"}}},"WebhookEventType":{"type":"string","enum":["collaboration-request.created","note.created"],"description":"V1 webhook event type short names. Only `collaboration-request.created` and `note.created`\nare delivered via V1 subscriptions. For the full set of 5 event types, use\n`POST /v2/webhooks` with `WebhookEventTypeV2` strings.\n"},"WebhookCaseDirection":{"type":"string","enum":["INBOUND","OUTBOUND"],"description":"Direction relative to the company that owns the webhook subscription.\nINBOUND means the subscribed company receives the case; OUTBOUND means it submits the case.\n"},"WebhookCallbackAuthDTO":{"type":"object","required":["type"],"properties":{"type":{"$ref":"#/components/schemas/WebhookCallbackAuthType"},"username":{"type":"string","maxLength":255,"description":"Required for BASIC. Sent as the username in the Basic Authorization header."},"password":{"type":"string","maxLength":255,"writeOnly":true,"description":"Required for BASIC. Write-only and never returned by the API."},"token":{"type":"string","maxLength":255,"writeOnly":true,"description":"Required for BEARER. This static token is sent on every delivery."},"headerName":{"type":"string","maxLength":255,"description":"Required for HEADER. The name of the custom header to send."},"headerValue":{"type":"string","maxLength":255,"writeOnly":true,"description":"Required for HEADER. Write-only value of the custom header to send."},"oauth2TokenUrl":{"type":"string","format":"uri","maxLength":500,"description":"Required for OAUTH2_CLIENT_CREDENTIALS. HTTPS OAuth2 token endpoint supporting the\nclient_credentials grant.\n"},"oauth2ClientId":{"type":"string","maxLength":255,"description":"Required for OAUTH2_CLIENT_CREDENTIALS. OAuth2 client identifier."},"oauth2ClientSecret":{"type":"string","maxLength":1024,"writeOnly":true,"description":"Required for OAUTH2_CLIENT_CREDENTIALS. Write-only OAuth2 client secret."},"oauth2ClientAuthenticationMethod":{"type":"string","enum":["CLIENT_SECRET_BASIC","CLIENT_SECRET_POST"],"default":"CLIENT_SECRET_BASIC","description":"OAuth2 client authentication method used at the token endpoint. `CLIENT_SECRET_BASIC`\nsends credentials using HTTP Basic authentication; `CLIENT_SECRET_POST` sends them in\nthe form body. Defaults to `CLIENT_SECRET_BASIC`.\n"},"oauth2Scope":{"type":"string","maxLength":500,"description":"Optional for OAUTH2_CLIENT_CREDENTIALS. Space-delimited OAuth2 scopes. When provided,\nthe value is normalized before storage and sent to the token endpoint as the `scope`\nparameter. If omitted, no scope parameter is sent.\n"}}},"WebhookCallbackAuthType":{"type":"string","enum":["NONE","BASIC","BEARER","HEADER","OAUTH2_CLIENT_CREDENTIALS"],"description":"Authentication type TSANet uses when delivering webhook events. Credentials are sent in\naddition to the X-Hub-Signature-256 HMAC header.\n\n- **NONE**: No callback authentication header.\n- **BASIC**: `Authorization: Basic `.\n- **BEARER**: `Authorization: Bearer ` using a static token.\n- **HEADER**: Sends the configured name and value as a custom header.\n- **OAUTH2_CLIENT_CREDENTIALS**: Obtains a short-lived access token from the configured\n OAuth2 token endpoint before delivery, then sends `Authorization: Bearer `.\n"},"WebhookSubscriptionResponseDTO":{"type":"object","properties":{"id":{"type":"integer","format":"int64"},"callbackUrl":{"type":"string","maxLength":500},"eventTypes":{"type":"array","items":{"$ref":"#/components/schemas/WebhookEventType"}},"caseDirections":{"type":"array","items":{"$ref":"#/components/schemas/WebhookCaseDirection"}},"partnerCompanyIds":{"type":"array","items":{"type":"integer","format":"int64"}},"payloadVersion":{"$ref":"#/components/schemas/WebhookPayloadVersion"},"active":{"type":"boolean"},"secret":{"type":"string","maxLength":64,"description":"HMAC secret for signing webhooks (only returned on creation; it cannot be rotated, so to change it, delete the subscription and create a new one)"},"callbackAuthType":{"$ref":"#/components/schemas/WebhookCallbackAuthType","description":"The authentication type configured for this subscription. Credential values are never returned."},"createdAt":{"type":"string","format":"date-time"}}},"WebhookPayloadVersion":{"type":"string","enum":["V1","V2"],"default":"V1","description":"Payload format version for webhook deliveries. See the Connect Webhook Events\nAsyncAPI specification for full payload and header details per version.\n- **V1** (default): Legacy flat JSON. Only `collaboration-request.created` and `note.created` are delivered.\n- **V2**: CloudEvents 1.0 structured binding. All 5 event types are delivered.\n"},"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"}}},"ProblemDetail":{"type":"object","properties":{"type":{"type":"string","format":"uri"},"title":{"type":"string"},"status":{"type":"integer","format":"int32"},"detail":{"type":"string"},"instance":{"type":"string","format":"uri"}},"additionalProperties":true}}},"paths":{"/v1/webhooks":{"post":{"tags":["WebhooksV1"],"summary":"Register a new V1 webhook subscription (legacy flat JSON)","deprecated":true,"description":"**Deprecated** — use `POST /v2/webhooks` instead.\nThis endpoint will be removed after 2027-01-01.\n\nSubscribe to receive legacy flat JSON webhook notifications for\n`collaboration-request.created` and `note.created` events.\n\nFor new integrations, prefer `POST /v2/webhooks` which delivers all 5 event types\nas CloudEvents 1.0 structured payloads.\n\n**Security**: Every delivery is signed with HMAC-SHA256. The signature is sent in the\n`X-Hub-Signature-256` header as `sha256=`. Verify it using the secret returned\non subscription creation. The secret cannot be rotated: to change it, delete the\nsubscription and create a new one.\n\n**Retries**: A `2xx` response counts as delivered. A `4xx` response is a permanent\nfailure and is not retried. Any other response (for example `5xx`), a connection error,\nor no response within 30 seconds is retried: each delivery gets up to 3 attempts in\ntotal (the first attempt plus 2 retries), 1 hour apart. After the third failed attempt\nthe delivery is moved to a dead-letter queue and is not attempted again automatically.\nEvery attempt is recorded as its own row in `GET /v1/webhooks/{id}/deliveries`.\nContact TSANet support about dead-lettered deliveries.\n","operationId":"createWebhookSubscription","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateWebhookSubscriptionRequestDTO"}}}},"responses":{"200":{"description":"Webhook subscription created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookSubscriptionResponseDTO"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}}}}}
```