Overview

When you configure a webhook, Printago sends an HTTP POST request to your URL each time a subscribed event occurs. Webhooks are configured via the Notification Settings API or the Printago dashboard under Settings → Notifications.

Delivery Format

Every webhook is delivered as an HTTP POST request with a JSON body. Your endpoint must respond with a 2xx status code to acknowledge receipt.

Payload Schema

All webhook payloads share a common envelope format:

{
  "event": string,       // The event name (e.g. "onJobSucceeded")
  "timestamp": string,   // ISO 8601 timestamp of when the event occurred
  "data": {
    "printer": Printer | null,     // Included for printer and job events
    "printJob": PrintJob | null    // Included for job events
  }
}

The data object contains the full Printer and/or PrintJob resource depending on the event type. These are the same objects returned by the GET /v1/printers/{id} and GET /v1/print-jobs/{id} endpoints respectively.

Printer Events

These events fire when a printer's status changes. The data.printer field contains the full Printer object.

{
  "event": "onPrinterOnline",
  "timestamp": "2026-03-13T14:30:00.000Z",
  "data": {
    "printer": {
      "id": "cm7abc123def456ghi",
      "name": "Bambu X1C #1",
      "model": "X1C",
      "status": "idle",
      "isOnline": true,
      ...
    },
    "printJob": null
  }
}

Print Job Events

These events fire when a print job changes status. The data.printJob field contains the full PrintJob object, and data.printer contains the printer the job is assigned to (if available).

{
  "event": "onJobSucceeded",
  "timestamp": "2026-03-13T16:45:00.000Z",
  "data": {
    "printer": {
      "id": "cm7abc123def456ghi",
      "name": "Bambu X1C #1",
      "model": "X1C",
      "status": "idle",
      "isOnline": true,
      ...
    },
    "printJob": {
      "id": "cm7xyz789ghi012jkl",
      "status": "Completed",
      "partName": "Benchy",
      "assignedPrinterId": "cm7abc123def456ghi",
      "startedAt": "2026-03-13T14:30:00.000Z",
      "completedAt": "2026-03-13T16:45:00.000Z",
      ...
    }
  }
}

Order Events

These events fire when orders are created, cancelled, or closed. Order events do not include printer or printJob data in the payload.

{
  "event": "onOrderCreatedRetail",
  "timestamp": "2026-03-13T10:15:00.000Z",
  "data": {
    "printer": null,
    "printJob": null
  }
}

Configuration

Configure webhooks via the API or the Printago dashboard.

1. Enable the webhook channel

{
  "channel": "webhook",
  "data": {
    "webhookUrl": "https://your-server.com/webhook",
    "apiKey": "your-secret-key-at-least-32-characters-long"
  }
}

2. Subscribe to events

{
  "onJobSucceeded": true,
  "onJobFailed": true,
  "onPrinterOffline": true,
  "onOrderCreatedRetail": true
}

Failure Handling

If your webhook endpoint returns a non-2xx status code or is unreachable, Printago logs the failure. If 10 or more failures occur within a 24-hour window, the webhook is automatically disabled to prevent further failed deliveries.