> 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.md).

# Webhooks

Webhook subscription management (delete, secret rotation, delivery log)

## Rotate the HMAC signing secret for a webhook subscription

> Generates a new HMAC-SHA256 secret for the subscription. The new secret is returned in the response and is \*\*only returned once\*\* — store it immediately.  After rotation, deliveries will be signed with the new secret. Allow a short overlap window before decommissioning the old secret on the consumer side. 

```json
{"openapi":"3.0.1","info":{"title":"OpenAPI definition","version":"v0"},"tags":[{"name":"Webhooks","description":"Webhook subscription management (delete, secret rotation, delivery log)"}],"servers":[{"url":"http://connect2.tsanet.org","description":"Generated server url"}],"security":[{"bearerAuth":[]}],"paths":{"/v1/webhooks/{id}/secret":{"post":{"tags":["Webhooks"],"summary":"Rotate the HMAC signing secret for a webhook subscription","description":"Generates a new HMAC-SHA256 secret for the subscription. The new secret is returned in the response and is **only returned once** — store it immediately.  After rotation, deliveries will be signed with the new secret. Allow a short overlap window before decommissioning the old secret on the consumer side. ","operationId":"rotateWebhookSecret","parameters":[{"name":"id","in":"path","description":"The webhook subscription ID","required":true,"schema":{"type":"integer","format":"int64"}}],"responses":{"200":{"description":"New HMAC secret generated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookSecretRotationResponseDTO"}},"application/problem+json":{"schema":{"$ref":"#/components/schemas/WebhookSecretRotationResponseDTO"}}}},"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":{"WebhookSecretRotationResponseDTO":{"type":"object","properties":{"id":{"type":"integer","description":"Webhook subscription ID","format":"int64"},"secret":{"type":"string","description":"New HMAC-SHA256 signing secret. This value is only returned once. Store it immediately — it cannot be retrieved again. "},"rotatedAt":{"type":"string","description":"Timestamp when the secret was rotated","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 (delete, secret rotation, delivery log)"}],"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"},"cloudEventId":{"type":"string"},"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 (delete, secret rotation, delivery log)"}],"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"}}}}}}
```