← Back to Guides
Webhooks
Subscribe to render events. Chart-Output sends an HTTP POST to your endpoint when a render succeeds, an async job finishes, or something fails on our side.
Events
render.success– A synchronous render finishedrender.complete– An async job (POST /api/v1/jobs) finishedrender.failed– A synchronous render hit an internal error, or an async job failed. Invalid chart specs are rejected with a 400 and do not send a webhook.
Payload format
All events follow the same envelope structure: event, timestamp, and a data object.
render.success
json
{
"event": "render.success",
"timestamp": "2024-01-15T12:00:00.000Z",
"data": {
"requestId": "req_abc123",
"chartType": "line",
"format": "png",
"width": 800,
"height": 400,
"renderTimeMs": 42
}
}render.failed
json
{
"event": "render.failed",
"timestamp": "2024-01-15T12:00:01.000Z",
"data": {
"requestId": "req_xyz789",
"error": "Internal error message",
"renderTimeMs": 5
}
}When an async job fails, data holds jobId and error instead of requestId.
render.complete
json
{
"event": "render.complete",
"timestamp": "2024-01-15T12:00:02.000Z",
"data": {
"jobId": "job_id_from_POST_jobs",
"resultUrl": "https://...",
"chartType": "bar",
"format": "png",
"renderTimeMs": 310
}
}Verification
Each webhook request includes an X-Signature header (HMAC-SHA256 of the raw body). Verify it using your webhook secret:
// Node.js
const crypto = require('crypto');
const expected = crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
if (expected !== req.headers['x-signature']) {
return res.status(401).send('Invalid signature');
}# Python
import hmac
import hashlib
expected = hmac.new(
secret.encode(),
raw_body,
hashlib.sha256
).hexdigest()
if expected != request.headers.get('X-Signature'):
return 'Invalid signature', 401Setup
Create webhooks from the Webhooks page in your dashboard. The secret is shown only at creation time. Each event is delivered once with a 10 second timeout; a failed delivery is not retried, so use GET /api/v1/jobs/:id to confirm a job's result if your endpoint was down.