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. Webhook security can be achieved through either API keys validation or mTLS. In addition, Paperbox can provision a static ip to allow ip whitelisting as an additional security layer.

Security

IP Whitelisting

The following IPs are used to communicate to your endpoint.

Production

IP Addresses
34.76.241.224	34.77.67.157	34.76.58.234

Acceptance

IP Addresses
34.140.187.100

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

Contract

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
}

Action Approve

tip

The payload changes depending on which action is performed and if it's applied onto a document or a mutation of that document.

Approve on a document

{
  "action": "approve",
  "processed_date": "2021-08-17T13:10:15.871311+00:00",
  "actor": "paperbox | john@doe.tld",
  "id": "944ccb4c-53f8-11eb-ab08-6fd8196e7291",
  "paperbox_id": "stri1wu7wmuctqwqto6zmjg61hmi0ng",
  "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": [
    {
      "MY_ENTITY": "my entity value"
      "type": "MY_ENTITY",
      "value": "my entity value",
      "confidence": 0.85
    }
  ],
  "topology": {
    "name": "string",
    "content_type": "application/rfc822"
    "parts": [
      {
        "id": "stri1wu7wmuctqwqto6zmjg61hmi0ng",
        "doc_type_name": "string",
        "doc_type_id": "string"
        "doc_subtype_name": "string",
        "doc_subtype_id": "string",
        "confidence": 0.72,
        "name": "string",
        "content_type": "text/html",
        "topology_type": "document" | "mail"
      }
    ]
  },
  "metadata": {
    "provider": {
      "MY_TRACING_ID": "MY-TRACING-VALUE"
    },
    "user": {
      "MY_DOCUMENT_METADATA": "MY_DOCUMENT_METADATA_VALUE"
    },
    "table": {
      "string": "string"
    }
  }
}

Approve on a mutation of a document with type copy

{
  "action": "approve",
  "processed_date": "2021-08-17T13:10:15.871311+00:00",
  "actor": "paperbox",
  "id": "944ccb4c-53f8-11eb-ab08-6fd8196e7291",
  "paperbox_id": "stri1wu7wmuctqwqto6zmjg61hmi0ng",
  "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": [
    {
      "MY_ENTITY": "my entity value"
      "type": "MY_ENTITY",
      "value": "my entity value",
      "confidence": 0.85
    }
  ],
  "topology": {
    "name": "string",
    "content_type": "application/rfc822"
    "parts": [
      {
        "id": "stri1wu7wmuctqwqto6zmjg61hmi0ng",
        "doc_type_name": "string",
        "doc_type_id": "string"
        "doc_subtype_name": "string",
        "doc_subtype_id": "string",
        "confidence": 0.72,
        "name": "string",
        "content_type": "text/html",
        "topology_type": "document" | "mail"
      }
    ]
  },
  "metadata": {
    "provider": {
      "MY_TRACING_ID": "MY-TRACING-VALUE"
    },
    "user": {
      "MY_DOCUMENT_METADATA": "MY_DOCUMENT_METADATA_VALUE"
    },
    "table": {
      "string": "string"
    }
  },
  "mutation_id": "qwejiqwe2389yjrwheriuy328ryjehr",
  "mutation_type": "copy" // DEPRECATED
}

Action Delete

tip

The payload changes depending on which action is performed and if it's applied onto a document or a mutation of that document.

Delete on a document

{
  "action": "delete",
  "processed_date": "2021-08-17T13:10:15.871311+00:00",
  "actor": "paperbox | john@doe.tld",
  "id": "944ccb4c-53f8-11eb-ab08-6fd8196e7291",
  "paperbox_id": "stri1wu7wmuctqwqto6zmjg61hmi0ng"
}

Delete on a mutation of a document with type copy

{
  "action": "delete",
  "processed_date": "2021-08-17T13:10:15.871311+00:00",
  "actor": "paperbox",
  "id": "944ccb4c-53f8-11eb-ab08-6fd8196e7291",
  "paperbox_id": "stri1wu7wmuctqwqto6zmjg61hmi0ng",
  "mutation_id": "qwejiqwe2389yjrwheriuy328ryjehr",
  "mutation_type": "copy" // DEPRECATED
}

Action Bounce

tip

The payload changes depending on which action is performed and if it's applied onto a document or a mutation of that document.

Bounce on a document

{
  "action": "bounce",
  "action_metadata": [
    {
      "type": "MY_EMAILADDRESS",
      "value": "john@doe.tld"
    }
  ],
  "processed_date": "2021-08-17T13:10:15.871311+00:00",
  "actor": "paperbox | john@doe.tld",
  "id": "944ccb4c-53f8-11eb-ab08-6fd8196e7291",
  "paperbox_id": "stri1wu7wmuctqwqto6zmjg61hmi0ng"
}

Bounce on a mutation of a document with type copy

{
  "action": "bounce",
  "action_metadata": [
    {
      "type": "MY_EMAILADDRESS",
      "value": "john@doe.tld"
    }
  ],
  "processed_date": "2021-08-17T13:10:15.871311+00:00",
  "actor": "paperbox",
  "id": "944ccb4c-53f8-11eb-ab08-6fd8196e7291",
  "paperbox_id": "stri1wu7wmuctqwqto6zmjg61hmi0ng",
  "mutation_id": "qwejiqwe2389yjrwheriuy328ryjehr",
  "mutation_type": "copy"
}