Webhooks

Webhooks push events to your HTTPS endpoint as they happen, so you do not need to poll. Every request is signed with your endpoint secret following the Standard Webhooks specification, retried for about 27 hours if your endpoint fails, and visible in a delivery log you can replay from the dashboard.

Create an endpoint

In the dashboard, open Webhooks, choose Add endpoint, enter your URL and pick the events you want. Or call the API with a key that has the admin scope:

curl https://api.printeasy.adfinite.com/v1/webhooks \
  -H "Authorization: Bearer $PRINTEASY_API_KEY" -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/printeasy/webhooks","description":"ERP print status","events":["printjob.done","printjob.error"]}'

The response includes the signing secret, which starts with whsec_. It is shown once and never again, so store it in your secret manager now. If you lose it, delete the endpoint and create a new one. Each endpoint belongs to one mode, the mode of the key that created it (or of the dashboard test mode toggle). It receives only events of that mode. URLs must be https: for live endpoints, must not contain a username or password, and must resolve to a public address. The check runs when you create or change an endpoint and again before every send, so an address that later points at a private network is refused. A URL that fails answers 422 invalid_url.

Event types

Event	Sent when
`printjob.queued`	A job is stored and waiting
`printjob.sent`	A job is pushed to the agent
`printjob.received`	The agent acknowledged the job
`printjob.printing`	The job reached the operating system spooler
`printjob.done`	The spooler finished the job
`printjob.error`	The job failed
`printjob.cancelled`	The job was cancelled
`printjob.expired`	The job was not received in time
`computer.online`	A computer’s agent connected
`computer.offline`	A computer’s agent disconnected
`printer.added`	A new printer appeared on a computer
`printer.removed`	A printer was removed from a computer
`printer.online`	A printer became available
`printer.offline`	A printer became unavailable
`printer.updated`	A printer’s settings changed

Subscribe an endpoint only to the events you handle. See Printing PDFs for what each job state means.

Payload

Every request body is a JSON envelope:

{
  "id": "0192f1a0-7c00-7000-8000-000000000001",
  "type": "printjob.done",
  "timestamp": "2026-10-14T10:00:00.000Z",
  "mode": "test",
  "data": {
    "id": "0192f1a0-7c00-7000-8000-0000000000aa",
    "printerId": "0192f1a0-7c00-7000-8000-0000000000bb",
    "title": "Invoice 1042",
    "state": "done",
    "stateMessage": null
  }
}

id identifies the event and is the same on every retry and replay. timestamp is when the event happened and mode is live or test. For printjob.* events, data is the print job object as GET /v1/printjobs/{id} returns it (the example is shortened). For computer.* events, data holds the computer id with its name and state. For printer.* events, data holds the printer id and the computerId it belongs to, with the details of the change.

Headers

Header	Value
`webhook-id`	The event id. Stable across retries and replays
`webhook-timestamp`	Unix seconds when this attempt was sent
`webhook-signature`	`v1,` followed by the base64 HMAC-SHA256 signature
`content-type`	`application/json`
`user-agent`	`PrintEasy-Webhooks/1.0`

Verify signatures

Always verify the signature before you trust a request. The SDKs check the signature and reject timestamps more than 300 seconds from now, which stops replayed requests.

import express from "express";
import { PrintEasy } from "@printeasy/sdk";

const pe = new PrintEasy({ apiKey: process.env.PRINTEASY_API_KEY });
const app = express();

app.post("/printeasy/webhooks", express.text({ type: "application/json" }), (req, res) => {
  try {
    pe.webhooks.verify(req.body, req.headers, process.env.PRINTEASY_WEBHOOK_SECRET!);
  } catch {
    return res.status(400).end();
  }
  const event = JSON.parse(req.body);
  if (event.type === "printjob.done") console.log("printed", event.data.id);
  res.status(204).end();
});

import json
import os

from flask import Flask, request
from printeasy import webhooks, WebhookVerificationError

app = Flask(__name__)

@app.post("/printeasy/webhooks")
def receive():
    body = request.get_data(as_text=True)
    try:
        webhooks.verify(body, request.headers, os.environ["PRINTEASY_WEBHOOK_SECRET"])
    except WebhookVerificationError:
        return "", 400
    event = json.loads(body)
    if event["type"] == "printjob.done":
        print("printed", event["data"]["id"])
    return "", 204

Verify the raw body exactly as received. Parsing and re-serialising the JSON changes the bytes and breaks the signature. In Express, read the body as text (as above) rather than through express.json().

Without the SDK, compute base64(HMAC-SHA256(key, "{webhook-id}.{webhook-timestamp}.{body}")), where key is the base64 decoded part of the secret after whsec_. Compare the result with each v1, entry of webhook-signature (the header can hold several, separated by spaces) using a constant time comparison, and reject timestamps more than 300 seconds from now.

import { createHmac, timingSafeEqual } from "node:crypto";

export function verifyManually(body: string, headers: Record<string, string>, secret: string, now = Math.floor(Date.now() / 1000)) {
  const id = headers["webhook-id"];
  const timestamp = headers["webhook-timestamp"];
  if (!id || !timestamp || Math.abs(now - Number(timestamp)) > 300) return false;
  const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64");
  const expected = createHmac("sha256", key).update(`${id}.${timestamp}.${body}`).digest("base64");
  return (headers["webhook-signature"] ?? "").split(" ").some((part) => {
    const [version, signature] = part.split(",");
    const a = Buffer.from(signature ?? "");
    const b = Buffer.from(expected);
    return version === "v1" && a.length === b.length && timingSafeEqual(a, b);
  });
}

Retries

Attempt 1 is sent immediately. A delivery succeeds when your endpoint answers with any 2xx status within 10 seconds. Anything else (another status, a timeout, a connection error) is a failure, and PrintEasy waits and tries again:

After failed attempt	Wait
1	5 seconds
2	30 seconds
3	2 minutes
4	10 minutes
5	30 minutes
6	2 hours
7	8 hours
8	16 hours

Each wait varies by plus or minus 20 percent (jitter). If attempt 9 also fails, the delivery is marked failed. A delivery is pending before its first send, retrying between attempts, succeeded after a 2xx and failed when attempts run out. Respond quickly and do the real work afterwards, for example by putting the event on a queue. Redirects are not followed.

Auto-disable after 5 days of failures

PrintEasy records when an endpoint started failing and clears that mark on any success. An endpoint whose deliveries keep failing for 5 days is disabled with the reason Disabled automatically after 5 days of failed deliveries, and every organization owner gets an email. Fix your receiver, then re-enable the endpoint in the dashboard (or PATCH /v1/webhooks/{id} with {"enabled": true}). Events produced while the endpoint was disabled are not sent to it; use the event feed to catch up.

Replays and duplicates

The delivery log in the dashboard (and GET /v1/webhooks/{id}/deliveries) shows every attempt with its status code and the start of the response. Replay a delivery from the dashboard or with POST /v1/webhooks/deliveries/{id}/replay. A replay sends the same event again with the same webhook-id. Replays need an enabled endpoint. Delivery is at least once, so a request can arrive more than once, and events can arrive out of order. Store the webhook-id values you have handled and skip repeats. Use the job state in data to ignore an older state that arrives after a newer one. Delivery logs are kept for 30 days.

Test mode endpoints

An endpoint created with a test key, or while the dashboard is in test mode, receives only test events, and may use an http: URL (for example a tunnel to your laptop). Use it with the virtual printers in Test mode to exercise your receiver end to end.

Event feed alternative

If you cannot expose an endpoint, poll GET /v1/events. It returns the events of your key’s mode, a page at a time. Use dir=asc with after set to the nextCursor of your previous call to read new events in order. Make the first call without after (an empty after= is rejected with 400):

curl "https://api.printeasy.adfinite.com/v1/events?dir=asc&limit=100" \
  -H "Authorization: Bearer $PRINTEASY_API_KEY"

Then pass the nextCursor you got back as after on each later call:

curl "https://api.printeasy.adfinite.com/v1/events?dir=asc&limit=100&after=$CURSOR" \
  -H "Authorization: Bearer $PRINTEASY_API_KEY"

The response has data, hasMore and nextCursor. When a page is empty, nextCursor is the after you sent, so you can keep polling with the same value. With dir=asc, an event shows up in the feed about 2 seconds after it happens. Keep after at the last event id you processed and poll again; do not skip ahead to a newer id, or you could miss an event that appears a moment later.

Get started

Printing

Build

SDKs

Migrate

Create an endpoint

Event types

Payload

Headers

Verify signatures

Retries

Auto-disable after 5 days of failures

Replays and duplicates

Test mode endpoints

Event feed alternative

​Create an endpoint

​Event types

​Payload

​Headers

​Verify signatures

​Retries

​Auto-disable after 5 days of failures

​Replays and duplicates

​Test mode endpoints

​Event feed alternative

Create an endpoint

Event types

Payload

Headers

Verify signatures

Retries

Auto-disable after 5 days of failures

Replays and duplicates

Test mode endpoints

Event feed alternative