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.

Fields

Our default response payload comes in JSON format and contains the following fields:

Parameter	Type	Optional	Description
action	string	false	One of 'approve', 'delete' or 'bounce'.
action_metadata	array	true	Metadata provided when a Paperbox user acted onto a document
processed_date	string	false	Document processing timestamp. ISO-formatted.
actor	string	false	User email or "paperbox" for automatically processed documents.
id	string	false	Document ID passed in the ingestion API
paperbox_id	string	false	Paperbox document ID. For referencing with Paperbox.
confidence	number	true	Classification confidence (not for deleted documents).
document_class	string	true	Document class.
document_subclass	string	true	Document subclass.
entities	array	true	Extracted entities.
metadata	object	true	The provider key value withholds document metadata passed in the ingestion API. Whilst the user key value withholds the information found during processing of the document within Paperbox
mutation_id	string	true	Mutation ID for copies or splits.
mutation_type	string	true	One of 'copy' or 'split'

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",
  "document_subclass": "string",
  "entities": [
    {
      "string": "string"
    }
  ],
  "metadata": {
    "provider": {
      "string": "string"
    },
    "user": {
      "string": "string"
    }
  },
  "mutation_id": "string",
  "mutation_type": "string"
}

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",
  "document_subclass": "string",
  "entities": [
    {
      "MY_ENTITY": "my entity value"
    }
  ],
  "metadata": {
    "provider": {
      "MY_TRACING_ID": "MY-TRACING-VALUE"
    },
    "user": {
      "MY_DOCUMENT_METADATA": "MY_DOCUMENT_METADATA_VALUE"
    }
  }
}

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",
  "document_subclass": "string",
  "entities": [
    {
      "MY_ENTITY": "my entity value"
    }
  ],
  "metadata": {
    "provider": {
      "MY_TRACING_ID": "MY-TRACING-VALUE"
    },
    "user": {
      "MY_DOCUMENT_METADATA": "MY_DOCUMENT_METADATA_VALUE"
    }
  },
  "mutation_id": "qwejiqwe2389yjrwheriuy328ryjehr",
  "mutation_type": "copy"
}

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"
}

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"
}