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

api_version
v2
endpoint
/v2/events.publish
method
POST
auth_scheme
Bearer