VeloSync API — events.publish

Reference for the events.publish endpoint of the VeloSync v2 webhooks API, including authentication, request schema, idempotency, and error codes.

Endpoint

POST https://api.velosync.dev/v2/events.publish. Requests require a bearer token in the Authorization header. Tokens are scoped per workspace and may be either a workspace.publish token (allowed) or a workspace.read token (rejected with 403). The endpoint accepts application/json only.

Request body

The request body must contain three required fields and may include three optional fields. Required: event_type (string, snake_case, max 64 characters), occurred_at (ISO 8601 timestamp with timezone), and payload (object, max 256 KB after JSON serialization). Optional: idempotency_key (string, max 128 characters), source (string), and trace_id (string).

Idempotency

When idempotency_key is supplied, VeloSync deduplicates retries within a 24-hour window per workspace. The first request succeeds and any subsequent request with the same key returns the original 200 response with the header X-VeloSync-Idempotent-Replay: true. Keys are case-sensitive and must contain only [A-Za-z0-9_-].

Errors

400 invalid_request returned for schema violations with a structured `errors[]` array. 401 missing_token and 403 insufficient_scope returned for auth failures. 409 idempotency_conflict returned when the same idempotency_key is reused with a different payload within the 24-hour window. 429 rate_limited returned with a Retry-After header when the per-token request rate of 200 requests per second is exceeded.

Key facts

The events.publish endpoint is POST https://api.velosync.dev/v2/events.publish.
The endpoint accepts only application/json content.
The request body has three required fields: event_type, occurred_at, and payload.
event_type must be snake_case and at most 64 characters.
Idempotency replays return the header X-VeloSync-Idempotent-Replay: true.
The per-token rate limit is 200 requests per second.
The payload is capped at 256 KB after JSON serialization.
Idempotency keys may only contain characters in the set [A-Za-z0-9_-] and are case-sensitive.
Reusing an idempotency key with a different payload within 24 hours returns 409 idempotency_conflict.

Details