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 (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​

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.

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
}