Connect your workspace. Keep the contract clear.

In Personal settings → API, create an expiring key bound to REST. Select the minimum scopes and projects your integration needs. Powerful keys require your password or an emailed confirmation code. Copy the one-time secret into your server’s secret manager.

Use the base URL shown by your instance, ending in /api/rest/v1. Send Authorization: Bearer with the personal key over HTTPS. Keep tokens out of browser code and URLs. Keys act as their owner; plan for ownership changes before a member leaves.

Follow next_cursor until has_more is false. For ticket sync use updated_since with order=updated_at:asc. The server keeps its sync_until timestamp fixed across pages and defers newer changes to the next sync. Finish all pages before saving sync_until as your next updated_since checkpoint. Subtract an overlap for long transactions and deduplicate by ID and updated_at. Numeric IDs remain stable when a project key changes.

Send a unique Idempotency-Key on create requests and reuse it for identical retries. Receipts last 24 hours. A different request with the same key returns 409. Honor Retry-After for in-flight requests and 429 responses.

Read application/problem+json errors by code. Keep X-Request-Id for diagnostics. Default per-replica limits are 120 requests and 60 writes per minute per key, and 600 per minute per workspace; operators can tune them. Inspect response headers and use bounded retries for temporary failures.

Preview responses carry X-API-Status: preview. Monitor the changelog and validate your client against the instance’s OpenAPI schema when upgrading. Generate your own client if useful; official SDKs are outside this Preview.

Keep the whsec_ secret on the receiver. Verify the original body bytes before JSON parsing. The Standard Webhooks libraries validate the signature and timestamp; use their default replay window and synchronize your receiver’s clock.

import { Webhook } from 'standardwebhooks';

// rawBody is the exact request body, before JSON parsing.
const verifiedEvent = new Webhook(process.env.WEBHOOK_SECRET).verify(
  rawBody,
  {
    'webhook-id': request.headers['webhook-id'],
    'webhook-timestamp': request.headers['webhook-timestamp'],
    'webhook-signature': request.headers['webhook-signature'],
  },
);
// Persist verifiedEvent and webhook-id atomically before returning 2xx.

import os
from standardwebhooks.webhooks import Webhook

# raw_body is the exact received body as bytes.
verified_event = Webhook(os.environ['WEBHOOK_SECRET']).verify(
    raw_body,
    dict(request.headers),
)
# Deduplicate and persist verified_event before acknowledging delivery.

import (
    "os"
    standardwebhooks "github.com/standard-webhooks/standard-webhooks/libraries/go"
)

verifier, err := standardwebhooks.NewWebhook(os.Getenv("WEBHOOK_SECRET"))
if err != nil { return err }
// body is the exact request body as []byte.
if err := verifier.Verify(body, request.Header); err != nil {
    return err // Reject the request; do not process its JSON.
}
// Deduplicate by request.Header.Get("webhook-id") and persist durably.

After verification, atomically record webhook-id with your work queue. Ignore IDs already processed, persist the event, and respond with 2xx promptly. Event order is not guaranteed. Retries and manual redelivery preserve the event ID and payload and use a fresh timestamp and signature.

During rotation both the current and previous secret sign deliveries for 24 hours. Update the receiver with the new secret before the overlap expires. Retain idempotency records for at least your redelivery window.

Use the endpoint delivery log to inspect attempts and redeliver failed events after repairing a receiver. Retained redelivery cannot recover events that were never emitted or are past retention; use updated_since API sync and deduplicate by resource ID and updated_at.

Events describe committed changes. Repeated writes in one transaction are coalesced into the final resource snapshot and net field changes. Project deletion does not emit child deletion events; deleting a ticket does not emit separate events for its removed comments. If data.truncated_fields lists omitted large text, fetch the resource through the API.

Library documentation: Node.js, Python, Go.