Developer Integration
Events and Idempotency
Duplicate suppression, metadata constraints, and queue safety.
Metadata Constraints
metadata must be a JSON object and is normalized to lowercase snake_case keys.
Validation rules:
- max 30 keys
- keys must match
^[a-z][a-z0-9_]{0,63}$ - payload size cap is 8192 serialized bytes
Idempotency Paths
Explicit idempotency
If idempotencyKey is provided, duplicate triggers are returned idempotently per (apiKeyId, idempotencyKey).
Windowed dedupe
When no explicit idempotency match exists, API computes a dedupe fingerprint and suppresses duplicates observed in a 15-second window.
Queue Safety
Job IDs are sanitized to avoid unsupported characters and include hashed segments where needed. This avoids BullMQ custom ID collisions and invalid-ID errors.