Overview

Introduction

Webhooks submit real-time user data to your own HTTP endpoints. A Webhook is an HTTP callback: a simple event-notification using HTTP POST. A web application implementing Webhooks will POST a message to a URL when certain things happen.

Getting started

  1. Go to Hub and click on Settings page
  2. On the right side of the page, your current Webhooks are displayed
  3. Click the "+" button
  4. Add the URL you would like to receive Webhooks to
  5. If you require authentication, add in a shared secret
Note: To assist with developing your integration with PrintedDirect webhooks, we recommend using a tool similar to Request Bin. This will allow you to fully inspect the headers and payload of our webhooks prior to integrating.

Actions

PrintedDirect dispatches webhooks for different actions, such as when Jobs progress through the system, or when a JobBatch is dispatched.

PrintedDirect does not currently allow subscribing to specific actions at this time. This means you will receive a webhook for every action that has a webhook defined for it. Update June 2025: We now have support for subscribing to specific webhook actions. Please contact us if you would like to use this feature._

To view the actions that PrintedDirect sends, with example payloads, see the Actions page.

Webhook failures and timeouts

When receiving a webhook, your service must respond within 10 seconds or PrintedDirect will log this is a timeout error and will re-attempt after some time.

PrintedDirect Webhook system abides by 429 Too Many Requests and will backoff and retry after a period of time. We will hold all new and pending webhooks to ensure they are delivered in chronological order once your system continues to accept our webhooks.

If we receive a non-2xx HTTP response code, we consider this a failure and will re-attempt it after some time. Therefore, it's important to always return a successful status even if you plan on discarding or ignoring the request. If you don't do this, we will continue to reattempt the failed webhook which will prevent newer webhooks from being delivered cause delays upstream.

Appendices

Authentication

If you want to authenticate the requests being sent to your webhook endpoint, you can specify a shared secret when creating your webhook. Once provided, PrintedDirect signs your requests using the shared secret and the body of the request, and add that as the X-Signature header. PrintedDirect calculates a SHA256 digest using the shared secret and the JSON-stringified body of the request.

An example of how one might authenticate the requests would be:

const signature = req.headers['x-signature'];
const digest = crypto
    .createHmac('sha1', settings.sharedSecret)
    .update(new Buffer(JSON.stringify(req.body), 'utf-8'))
    .digest('hex');

if (signature === digest) {
    // payload verified.
}

SSL certificates

PrintedDirect webhooks are incompatible with self-signed certificates. If we detect a self-signed certificate, it will generate an error, preventing any requests from being sent.

Table of Contents