Webhook Events

What TSANet Connect sends to your endpoint, and how to verify it.

The Webhooks V1 and Webhooks V2 pages cover how to subscribe. This page covers what Connect actually delivers to your endpoint once you have.

Payload versions

Version	Subscribe with	Events	Format
V2	POST /v2/webhooks	All 5 event types	CloudEvents 1.0 structured
V1 (legacy)	POST /v1/webhooks	collaboration-request.created, note.created	Flat JSON

V1 is frozen — no new events or fields will ever be added to it, and it is scheduled for removal after 2027-01-01. Use POST /v2/webhooks for new integrations.

Event types (V2)

CloudEvent type	Fired when	data fields
org.tsanet.connect.collaboration-request.created	A collaboration request is submitted	requestToken
org.tsanet.connect.collaboration-request.closed	A collaboration request is closed	requestToken
org.tsanet.connect.collaboration-request.note.created	A note is added	requestToken, noteToken
org.tsanet.connect.collaboration-request.response.created	An approval, rejection, information request, or information response is created	requestToken, responseId
org.tsanet.connect.collaboration-request.response.updated	An existing response is revised	requestToken, responseId

Payloads are deliberately thin. Use the tokens to fetch the full record from the REST API — for a response, responseId tells you which record to fetch to determine its type and status.

Delivery headers

Header	Value
Content-Type	application/cloudevents+json (V2) or application/json (V1)
X-Hub-Signature-256	sha256=<64 hex chars> — HMAC of the raw body
X-Connect-Delivery	The CloudEvent id. Use as your idempotency key.
X-Connect-Event	The CloudEvent type. Lets you route without parsing the body.

X-Connect-Delivery and X-Connect-Event mirror the id and type fields in the body, so you can route and deduplicate at the HTTP layer.

Verifying signatures

Every delivery is signed with HMAC-SHA256 over the raw request body, using your subscription secret. Always verify before processing.

Node.js

const crypto = require('crypto');

function verify(rawBody, signatureHeader, secret) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(rawBody)          // the raw bytes, before any JSON parsing
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signatureHeader)
  );
}

Compute the HMAC over the raw body bytes. Re-serialising the parsed JSON changes the byte sequence and the signature will not match. Compare with a constant-time function, never ===.

Your secret is returned once, when the subscription is created. Rotate it with POST /v1/webhooks/{id}/secret — the new secret is likewise returned only once. Allow a short overlap before retiring the old one.

Delivery guarantees

• At-least-once. Your endpoint may receive the same event more than once. Deduplicate on the CloudEvent id (V2) or on requestToken + eventType + timestamp (V1). The id is stable across redeliveries.

• Timeout. Respond within 30 seconds. Acknowledge first, process afterwards.

• Retries. 5xx responses and network timeouts trigger redelivery. Two retries are attempted, with a 1-hour delay between each. 4xx responses are treated as permanent failures and are not retried.

• Dead-letter. Deliveries that exhaust every retry are moved to a dead-letter queue and flagged in the delivery log. Contact TSANet Support to replay them.

Inspect delivery history with GET /v1/webhooks/{id}/deliveries.

Subscription filters

A subscription can narrow what it receives by eventTypes, caseDirections, and partnerCompanyIds. Omitting a filter means it is not applied.

Directions are relative to the company that owns the subscription:

• INBOUND — your company receives the collaboration request.

• OUTBOUND — your company submits it.

Event type strings must match the CloudEvent type exactly as delivered, for example org.tsanet.connect.collaboration-request.created.

Source identifier

The CloudEvent source field identifies the environment that sent the event:

Environment	source
Production	https://connect2.tsanet.us
Beta	https://connect2.tsanet.net

The subscriptionid field carries the ID of the subscription the event was delivered to — useful when several subscriptions point at the same endpoint.