Signed webhooks
Receive render completion, failure and cancellation events without aggressive polling.
Create an endpoint with the event types you need:
curl -X POST "$JSONCUT_API/api/v2/webhooks" \
-H "X-API-Key: $JSONCUT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"Production renders","url":"https://example.com/jsoncut-events","eventTypes":["render.completed","render.failed","render.cancelled"]}'The signing secret is returned once. Store it securely.
Verify a delivery
JsonCut sends:
X-JsonCut-Event-IdX-JsonCut-TimestampX-JsonCut-Signature
X-JsonCut-Timestamp is a Unix time in seconds. Compute HMAC-SHA256 over <timestamp>.<raw-body> using the endpoint secret, as a hex digest. Compare it with the v1= signature using a constant-time comparison. Verify the raw request bytes before parsing JSON, reject stale timestamps, and deduplicate event IDs.
The JSON body has the shape { "id", "type", "createdAt", "data" }, where type is render.completed, render.failed or render.cancelled and data describes the render.
import crypto from 'node:crypto';
const expected = `v1=${crypto
.createHmac('sha256', process.env.JSONCUT_WEBHOOK_SECRET)
.update(`${timestamp}.${rawBody}`)
.digest('hex')}`;
const valid = expected.length === signature.length
&& crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));Delivery operations
GET /api/v2/webhooks/{id}/deliveriesreturns recent safe delivery state without downstream response bodies.POST /api/v2/webhooks/{id}/testcreates one signed test event.POST /api/v2/webhooks/{id}/deliveries/{deliveryId}/replayretries a dead-letter delivery while preserving its event identity.
Respond with a 2xx status within 10 seconds and process work asynchronously. Any other status, a timeout or a connection error schedules a retry with exponential backoff, starting at 5 seconds. After 6 failed attempts the delivery becomes dead-letter and stays there until you replay it.
The number of webhook endpoints depends on the plan: Hobby 1, Pro 5, Business 20.