# Webhooks Webhook subscription management for event notifications ## GET /v1/webhooks > List webhook subscriptions for the current company ```json {"openapi":"3.0.1","info":{"title":"OpenAPI definition","version":"v0"},"tags":[{"name":"Webhooks","description":"Webhook subscription management for event notifications"}],"servers":[{"url":"http://connect2.tsanet.org","description":"Generated server url"}],"security":[{"bearerAuth":[]}],"paths":{"/v1/webhooks":{"get":{"tags":["Webhooks"],"summary":"List webhook subscriptions for the current company","operationId":"listWebhookSubscriptions","responses":{"200":{"description":"List of webhook subscriptions","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/WebhookSubscriptionDTO"}}},"application/problem+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/ErrorResponse"}}}}}}}},"components":{"schemas":{"WebhookSubscriptionDTO":{"type":"object","properties":{"id":{"type":"integer","format":"int64"},"callbackUrl":{"type":"string"},"eventTypes":{"type":"array","items":{"type":"string","enum":["collaboration-request.created","note.created"]}},"active":{"type":"boolean"},"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 webhook subscription > Subscribe to receive webhook notifications for specific events. When an event occurs, a WebhookPayload will be sent via HTTP POST to your callback URL. \*\*Security\*\*: The webhook payload is signed using HMAC-SHA256. The signature is sent in the \`X-Hub-Signature-256\` header as \`sha256=\\`. Verify the signature using the secret returned upon subscription creation. \*\*Payload\*\*: See WebhookPayload schema for the structure of events sent to your endpoint. \*\*Retries\*\*: Failed deliveries are retried up to 3 times with exponential backoff (10s, 60s, 300s). ```json {"openapi":"3.0.1","info":{"title":"OpenAPI definition","version":"v0"},"tags":[{"name":"Webhooks","description":"Webhook subscription management for event notifications"}],"servers":[{"url":"http://connect2.tsanet.org","description":"Generated server url"}],"security":[{"bearerAuth":[]}],"paths":{"/v1/webhooks":{"post":{"tags":["Webhooks"],"summary":"Register a new webhook subscription","description":"Subscribe to receive webhook notifications for specific events. When an event occurs, a WebhookPayload will be sent via HTTP POST to your callback URL. **Security**: The webhook payload is signed using HMAC-SHA256. The signature is sent in the `X-Hub-Signature-256` header as `sha256=`. Verify the signature using the secret returned upon subscription creation. **Payload**: See WebhookPayload schema for the structure of events sent to your endpoint. **Retries**: Failed deliveries are retried up to 3 times with exponential backoff (10s, 60s, 300s). ","operationId":"createWebhookSubscription","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateWebhookSubscriptionRequestDTO"}}},"required":true},"responses":{"200":{"description":"Webhook subscription created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookSubscriptionResponseDTO"}},"application/problem+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/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"schemas":{"CreateWebhookSubscriptionRequestDTO":{"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 event types to subscribe to. If empty or null, all events will be delivered. Available event types: - collaboration-request.created: Triggered when a new collaboration request is created - note.created: Triggered when a note is added to a collaboration request ","items":{"type":"string","description":"Optional list of event types to subscribe to. If empty or null, all events will be delivered. Available event types: - collaboration-request.created: Triggered when a new collaboration request is created - note.created: Triggered when a note is added to a collaboration request ","enum":["collaboration-request.created","note.created"]}}}},"WebhookSubscriptionResponseDTO":{"type":"object","properties":{"id":{"type":"integer","format":"int64"},"callbackUrl":{"type":"string"},"eventTypes":{"type":"array","items":{"type":"string","enum":["collaboration-request.created","note.created"]}},"active":{"type":"boolean"},"secret":{"type":"string","description":"HMAC secret for signing webhooks (only returned on creation)"},"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"}}}}}} ``` ## GET /v1/webhooks/{id}/deliveries > Get delivery log for a webhook subscription ```json {"openapi":"3.0.1","info":{"title":"OpenAPI definition","version":"v0"},"tags":[{"name":"Webhooks","description":"Webhook subscription management for event notifications"}],"servers":[{"url":"http://connect2.tsanet.org","description":"Generated server url"}],"security":[{"bearerAuth":[]}],"paths":{"/v1/webhooks/{id}/deliveries":{"get":{"tags":["Webhooks"],"summary":"Get delivery log for a webhook subscription","operationId":"getWebhookDeliveries","parameters":[{"name":"id","in":"path","description":"The webhook subscription ID","required":true,"schema":{"type":"integer","format":"int64"}},{"name":"page","in":"query","description":"Page number (0-based)","required":false,"schema":{"type":"integer","format":"int32","default":0}},{"name":"size","in":"query","description":"Page size","required":false,"schema":{"type":"integer","format":"int32","default":20}}],"responses":{"200":{"description":"Delivery log","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookDeliveryLogPageDTO"}},"application/problem+json":{"schema":{"$ref":"#/components/schemas/WebhookDeliveryLogPageDTO"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Webhook subscription not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"schemas":{"WebhookDeliveryLogPageDTO":{"type":"object","properties":{"content":{"type":"array","items":{"$ref":"#/components/schemas/WebhookDeliveryLogDTO"}},"totalElements":{"type":"integer","format":"int64"},"totalPages":{"type":"integer","format":"int32"},"size":{"type":"integer","format":"int32"},"number":{"type":"integer","format":"int32"}}},"WebhookDeliveryLogDTO":{"type":"object","properties":{"id":{"type":"integer","format":"int64"},"integrationId":{"type":"integer","format":"int64"},"eventType":{"type":"string"},"httpStatus":{"type":"integer","format":"int32"},"attemptNumber":{"type":"integer","format":"int32"},"success":{"type":"boolean"},"requestBody":{"type":"string"},"responseBody":{"type":"string"},"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"}}}}}} ``` ## DELETE /v1/webhooks/{id} > Delete a webhook subscription ```json {"openapi":"3.0.1","info":{"title":"OpenAPI definition","version":"v0"},"tags":[{"name":"Webhooks","description":"Webhook subscription management for event notifications"}],"servers":[{"url":"http://connect2.tsanet.org","description":"Generated server url"}],"security":[{"bearerAuth":[]}],"paths":{"/v1/webhooks/{id}":{"delete":{"tags":["Webhooks"],"summary":"Delete a webhook subscription","operationId":"deleteWebhookSubscription","parameters":[{"name":"id","in":"path","description":"The webhook subscription ID","required":true,"schema":{"type":"integer","format":"int64"}}],"responses":{"204":{"description":"Webhook subscription deleted successfully"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Webhook subscription not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"schemas":{"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"}}}}}} ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://tsanet.gitbook.io/connect/api-reference/webhooks.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.