Webhooks

Webhooks reduce polling but do not replace authoritative resource reads. A receiver must authenticate the event, tolerate delivery behavior and fetch current state when ordering matters.

Signing

Verify the signature against the exact raw request bytes before parsing JSON. Keep active and next verification material during rotation and reject algorithms or key IDs outside the configured endpoint contract.

Tolerance

Enforce the documented timestamp tolerance while allowing ordinary network delay. Synchronize receiver clocks and reject stale signed requests outside the window.

Duplicates

Delivery is at least once. Store the event ID and make handling idempotent. A duplicate event must not create a duplicate catalog action or notification.

Ordering

Events can arrive out of order. Treat the referenced batch, item or job resource as authoritative and compare its current version or state before applying local transitions.

Rotation

Rotate endpoint secrets without a blind gap: add the new verifier, update Kasty, observe successful signed delivery, then retire the old verifier.

Retries

Return success only after the receiver durably records the event or equivalent work. Apply bounded backoff internally and avoid long synchronous downstream operations in the webhook request.

Replay

When replay is supported operationally, it re-delivers the same immutable event identity. Replay does not create a new Kasty state transition.

Endpoint safety

Use HTTPS, a dedicated route, strict body limits and no open redirect. The canonical webhook envelope is represented by receiveMusicDeliveryStatusWebhook and synthetic events.