Skip to main content
← 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 finished
  • render.complete – An async job (POST /api/v1/jobs) finished
  • render.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'); }

Setup

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.