Webhooks

To avoid the need for polling, which is inefficient and non-robust, RPI Print API supports sending webhooks (HTTP notifications) out on certain order events. These can be activated by setting webhookUrl property when creating new order.

Notifications are sent in a reliable manner (several retries with backoff), so can be used to keep track of an order's progress.

The content of notifications is always JSON, describing the order, much like if you performed a GET request on it.

Notifications are configured in the create order request by using the webhookUrl property:

{
 "webhookUrl": "https://endpoint.com/callbacks/741231"
}

webhookUrl can be set to a different URL for each created order and may include query parameters, for example ?orderid=1234. During development you might want to use one of the webhook testing services, such as https://webhook.site or https://ngrok.com/.

An improperly formatted webhookUrl will result in order creation failure. The URL must satisfy the following requirements:

• The webhookUrl must be a valid URL.
• webhookUrl must start with the https:// prefix. Any other protocol will not be accepted.
• webhookUrl must be publicly accessible via the internet.
• You must have control over the URL.
• The URL should not point to "localhost" or use any private IP addresses such as those in the 192.168.x.x or 10.x.x.x ranges. These are typically reserved for private networks and are not accessible over the public internet.

Webhook request

The webhook request that is sent to your endpoint has a JSON body with this structure:

property name	type	description
source	string	The "source" of an event that triggered the sending of this webhook
time	string	Timestamp of webhook event, in UTC, ISO-8601 format
data	object	This is almost always an OrderFullResponse as described in the API Reference.

The only exception for the data property is when an error happens before the order is accepted by Print API. Generally, such an error means the order could not be created, so Print API doesn't have the necessary data to populate a OrderFullResponse.

In this case the source will be OrderStoring, and the contents will be a JSON payload with these properties:

property	type	description
fullOrderId	string	The "full" order id is a combination of your 'Customer Name' and the customerOrderId, joined with the / character: {customerPublicId}/{customerOrderId}}
customerOrderId	string	Unique identifier for an order
message	string	A message describing why the order could not be created / was not accepted by Print API

List of webhook sources

source	event that causes this webhook
OrderAcceptedByPrinter	Order has been accepted by the printer, this marks the start of printing process. Cancellation requests might fail from this point forward.
OrderAssetsAllProcessed	All print assets that order contains have been successfully processed
OrderCancellationRequestSentToPrinter	Order is already in printing state and order cancellation has been sent to the printer. Waiting for confirmation or rejecton for cancellation.
OrderCancelledBeforeSubmissionToPrinter	Order has been cancelled before it has been sent to printing.
OrderCancelled	Order has been successfully cancelled.
OrderCreated	Order has passed initial validation and has been queued for further processing.
OrderEnteredHoldingBin	Order has entered holding bin. Order will stay in holding bin for approximately 3 hours. During this time window cancellation will always succeed.
OrderErrorAtPrinter	There was an issue printing the order, please check order details for more information or contact CS
OrderExceedsLimitQueue	Order has exceeded the daily limit and over-the-limit queue and has been rejected. Order will not be processed.
OrderExitedHoldingBin	Order has exited holding bin after 3 hours or after manual approval by CS support and has been scheduled to be send to the pinter.
OrderExitedLimitQueue	Order that has been over the daily order limit has been released to normal workflow.
OrderFailed	Order print asset processing has failed, usually that means there is an issue with submitted print assets. Check order validation responses for more details.
OrderFinishedPricing	Order has pricing & taxes applied and those fields are now available.
OrderInExceptionState	Order has entered EXCEPTION state. This state usually requires CS support to resolve.
OrderOverLimitQueued	This order has been placed in limit queue as more than maximum amount of orders have been submitted the last 24 hours.
OrderReceived	Order has been received by the system and is queued for initial validation.
OrderReprintRequested	Reprint of this order has been created.
OrderShipped	Order has been shipped. Orders can be shipped in single or multiple shipments. When last shippment is sent this marks the end of the order workflow.
OrderShippingEstimatesRefreshed	Shipping estimates have been updated for this order before sending to printer. Shippment date might have changed due to time order spent in limited queue or in holding bin.
OrderSubmittedToPrinter	Order has been sent to the printer and is waiting for confirmation by the printer.
OrderValidationFailed	Order validation failed. Check validation responses on the order for more details.
OrderVoidedByPrinter	Order that has already entered printing state has been successfuly cancelled.
PaymentFailure	Payment has failed. Scheduled payments will be retried the next day. Verify your payment information.
PaymentSuccessful	Payment has been successful, orders waiting for payment will move to holding bin

Webhook response

Webhook endpoint should respond with HTTP Status between 200 and 299 (2XX) and should ideally take less than 10 seconds to respond. In case any of these conditions are not met, webhook sending will be retried at a later time. In case of continuous failures webhook sending will be retried a number of times, after which the specific webhook event will be marked as failed.

All sent webhooks for an order are listed on the Order Details page (Callbacks section) in the RPI Dashboard. (Failed attempts are also listed in the Dashboard along with the reason for the failure, e.g., "404 Not Found" if your endpoint responded with this HTTP status.)

Webhook signature

The webhook request body is signed with an hmac-sha256 signature to prevent tampering and to make sure webhook was sent by RPI Print API. The Signature is sent as a Base64 encoded hash value in the webhook HTTP request header x-rpi-printapi-hmac-sha256.

Webhook Secret can be obtained from the RPI Dashboard, API Credentials section.

Example: Calculate hmac-sha256 in nodejs

import { createHmac } from "crypto" 
...
const hmacSignature = createHmac('sha256', webHookSecret).update(webhookReceivedBodyAsString, 'utf8').digest('base64');

List of