Skip to main content

Webhook

Paperbox supports webhooks as a way of extending the platform and listening for the state of documents. These webhooks are registered to receive callbacks from Paperbox for each document that is approved, either manually or automatically, or deleted.

Each Paperbox inbox can be equipped with one or more webhooks. Each webhook should be accessible through a HTTP endpoint that accepts a JSON payload (containing the Paperbox processed document, see below for examples) with a POST method.

Webhook security can be achieved through

  • API keys authentication

    • The API key to use for calling the HTTP endpoint can be configured in the Paperbox Webhooks configuration as a custom HTTP header (e.g. X-API-KEY) or as part of the URL query parameters (e.g. ?api_key=)
    • The HTTP endpoint must validate that the incoming request from Paperbox contains the correct API key before accepting the JSON payload.

  • Mutual TLS authentication with the Paperbox certificate or with your own client certificate (see below for details).

  • In combination with one of the previous options, an additional security layer can be added by whitelisting only the Paperbox provided static IP addresses (see below).

This allows the webhook to authenticate and send a JSON payload in a single call. Paperbox webhooks do not support additional HTTP call for authentication and authorization.

Security​

IP Whitelisting​

The following IPs are used to communicate to your endpoint.

IP Addresses
34.76.241.22434.77.67.15734.76.58.234

mTLS​

Paperbox sends one client certificate when it connects to your webserver. Each HTTP connector uses the Paperbox certificate (the default) or a client certificate that you upload.

Paperbox certificate (default)​

We include our Public TLS Certificate when connecting to your webserver. Meaning you can pin that certificate to verify authenticity of our message. If you choose to do so you will have to take part in our yearly certificate rotation process. To enroll, please send us an email via support@paperbox.ai or send us a message via your Paperbox workspace.

Your own client certificate​

Use this option if your webserver accepts only client certificates that your certificate authority (CA) signed. For that connector, Paperbox sends your certificate instead of the Paperbox certificate.

To add your certificate:

  1. In the Paperbox admin, go to Connectors and open the HTTP connector of your webhook.
  2. In the Client certificate section, upload one of these files:
    • A .pfx or .p12 file. Type the password of the file.
    • A .pem file that contains the certificate and the private key. If the private key is encrypted, type its password.
  3. Save the connector.

When you save the connector, Paperbox reads the file one time. Paperbox keeps the certificate and the private key as a secret. Paperbox does not keep the password.

Paperbox refuses the file if:

  • The password is incorrect, or Paperbox cannot read the file.
  • The file does not contain a private key.
  • The file does not contain a certificate for the private key.
  • The certificate is expired or is not valid yet.

After you save the connector, the connector settings show the subject and the expiry date of your certificate.

caution

Paperbox does not renew your certificate. To replace (rotate) the certificate before the expiry date, click the remove button (X) next to the stored certificate, select the new file, type its password if it has one, and save the connector.

JSON Examples​

tip

Optional fields, depending on which action or type of document get included in the webhook payload, are highlighted in yellow.

{
  "action": "string",
  "action_metadata": [
    {
      "type": "string",
      "value": "string"
    }
  ],
  "processed_date": "string",
  "actor": "string",
  "id": "string",
  "paperbox_id": "string",
  "confidence": "float",
  "document_class": "string", // DEPRECATED
  "document_subclass": "string", // DEPRECATED
  "bundle_type_name": "string",
  "bundle_type_id": "string",
  "bundle_subtype_name": "string",
  "bundle_subtype_id": "string",
  "entities": [
    {
      "string": "string", // DEPRECATED
      "type": "string",
      "value": "string",
      "confidence": "string"
    }
  ],
  "topology": {
    "name": "string",
    "content_type": "string",
    "parts": [
      {
        "id": "string",
        "doc_type_name": "string",
        "doc_type_id": "string"
        "doc_subtype_name": "string",
        "doc_subtype_id": "string",
        "confidence": "float",
        "name": "string",
        "content_type": "string",
        "topology_type": "document" | "mail"
      }
    ]
  },
  "metadata": {
    "provider": {
      "string": "string"
    },
    "user": {
      "string": "string"
    },
    "table": {
      "string": "string"
    }
  },
  "mutation_id": "string",
  "mutation_type": "string" // DEPRECATED
}