Teambridge External API (0.1.0)

Returns metadata about all collections for the account associated with the provided access token.

Returns all field definitions for a collection, including field identifiers, names, types, write format hints, select options (for native selects), and linked collection IDs (for link-to-object fields). Use this endpoint to discover the schema before reading or writing records.

Returns a paginated list of records for a collection. Each record is represented as a map of field UUIDs to values. Use the /fields endpoint first to get field metadata (names, types, write format hints) to interpret the data.

Filtering Support: This endpoint supports filtering via query parameters in the format {fieldUUID}_{operator}={value}.

• Up to 10 filters per request with implicit AND logic (all filters must match)
• Use the /fields endpoint to discover field UUIDs
• See the API description above for detailed filtering documentation and examples

Supported Operators by Field Type:

• TEXT: _is (exact), _contains (partial match)
• NUMBER: _is, _gt, _gte, _lt, _lte
• DATETIME: _is, _gt, _gte, _lt, _lte
• BOOLEAN: _is
• SINGLE_SELECT/MULTI_SELECT: _is
• Default: No suffix defaults to _is behavior

Filter Examples:

• Filter by email: ?{email-field-uuid}_is=john@example.com
• Filter by partial name: ?{name-field-uuid}_contains=john
• Filter by date range: ?{date-field-uuid}_gte=2025-01-01&{date-field-uuid}_lte=2025-12-31
• Filter by age range: ?{age-field-uuid}_gte=21&{age-field-uuid}_lte=65
• Multiple filters: ?{field1-uuid}_is=value1&{field2-uuid}_contains=value2

Creates a new record in the collection. The request body should contain a map of field UUIDs to string values. Use the /fields endpoint to discover field IDs and their expected write formats (writeFormatHint).

Returns a single record identified by its UUID. The record is represented as a map of field UUIDs to values. Use the /fields endpoint to get field metadata.

Updates an existing record. The request body should contain a map of field UUIDs to string values for the fields you want to update. Only include fields that need to be changed. Use the /fields endpoint to discover field IDs and write formats.

Uploads a document file with optional metadata for the authenticated account.

Important: This endpoint requires multipart/form-data content type for file upload.

Limits:

• Maximum file size: 100MB
• Maximum roles per document: 10

The request consists of two parts:

• file: The document file to upload (required)
• request: JSON metadata for the document (optional)

Returns a list of all supported timezone identifiers, sorted alphabetically.

Returns all external system mappings for a specific Teambridge record. Mappings link records to external system entities.

Creates a new mapping linking a Teambridge record to an external system entity. Each mapping associates a record with an external provider, external ID, and object type.

Updates the external ID for an existing mapping. This is useful when the external system ID changes but the mapping relationship should be preserved.

Deletes an external system mapping. This removes the link between a Teambridge record and an external system entity without affecting the underlying record.

Subscribe to events in Teambridge to receive real-time notifications when your data changes.

Account owners: configure your webhook subscriptions inside Settings > Account | Outbound webhooks

Choose a publicly-accessible HTTPS endpoint where we should send events. Select the events to which you would like to subscribe.

When you save the webhook subscription, a modal will show you your HMAC secret. Store this somewhere safe. The secret key lets you validate that events published to your endpoint come from us. If you lose your secret, you can rotate it and receive a new one.

Security

All webhook requests include HMAC-SHA256 signatures for verification. The signature lets you know that this event came from Teambridge.

Request Headers:

• X-Webhook-Signature: HMAC-SHA256 signature with sha256= prefix (e.g., sha256=abc123...)
• X-Webhook-Timestamp: Unix timestamp in seconds (when the webhook was sent)
• Content-Type: application/json

Signature Verification:

1. Extract the X-Webhook-Timestamp and X-Webhook-Signature headers from the request
2. Strip the sha256= prefix from the signature header
3. Construct the signed payload: {timestamp}.{request_body} (use the raw request body string, not parsed JSON)
4. Compute HMAC-SHA256 of the signed payload using your webhook secret
5. Compare the computed signature with the provided signature using constant-time comparison
6. Reject requests with timestamps more than 5 minutes old (prevents replay attacks)

Example Verification (Node.js):

First, check that the timestamp is recent (within 5 minutes):

const timestamp = request.headers['x-webhook-timestamp'];
const currentTime = Math.floor(Date.now() / 1000);

if (Math.abs(currentTime - timestamp) > 300) {
  throw new Error('Webhook timestamp too old');
}

Then, compute the expected signature and compare. Note that you must use the raw request body string, not parsed JSON:

const crypto = require('crypto');
const signatureHeader = request.headers['x-webhook-signature'];
const signature = signatureHeader.replace('sha256=', '');
const rawBody = request.rawBody;

const signedPayload = `${timestamp}.${rawBody}`;
const expectedSignature = crypto
  .createHmac('sha256', secret)
  .update(signedPayload)
  .digest('hex');

if (!crypto.timingSafeEqual(
  Buffer.from(signature),
  Buffer.from(expectedSignature)
)) {
  throw new Error('Invalid webhook signature');
}

Secret Management

• All webhook subscriptions for an account share the same secret key
• Secrets are only shown once when first created or rotated
• During rotation, update your verification code with the new secret
• Store secrets securely (environment variables, secret managers)

Consuming Webhooks

Best Practices:

1. Respond quickly - Return 200 OK within 5 seconds to avoid retries
2. Process asynchronously - Queue the webhook for background processing
3. Verify signatures - Always validate the HMAC signature before processing
4. Check timestamps - Reject old webhooks to prevent replay attacks
5. Handle idempotently - Use event_id to deduplicate events
6. Return appropriate status codes:
   • 200 OK - Webhook received and verified successfully
   • 400 Bad Request - Invalid signature or expired timestamp
   • 500 Internal Server Error - Processing error (will trigger retry)

Payload Versioning

The webhook payload format is versioned. The current version is 1.0 (see the version field in the payload).

• Breaking changes will increment the version number
• Non-breaking additions (new optional fields) do not change the version
• Parse the version field to handle different payload formats
• Version changes will be announced in advance via release notes

Retry Behavior

If your endpoint does not return 200 OK, Teambridge will retry the webhook

• Maximum retry attempts: 5
• Webhooks are marked as failed after all retries are exhausted
• Contact support to replay failed webhooks if needed