Send notifications to third-party services

[Tooa]

I would like to receive the import successful or import failed notification introduced in v1.1.0 on my phone as push notification. I know there is a variety of applications such as discord, telegram, etc. users might want to receive their notifications to. But this discussion is about receiving the notifications to a so called web hook endpoint. The receiving end then forwards the notification to the platform of interest.

Workflow is as follows then:

• I scan a document with my phone and upload it to a WebDAV target that is configured as input folder for paperless-ng
• Paperless sends the import result (success or failure) as POST request to the configured web hook endpoint
• The configured endpoint service receives the POST request and takes care of sending the notification to the desired communication platform like discord, telegram, raw push notifications etc.
• I receive the notification on my phone and know whether the import was successful or not
• Depending on the import outcome I can throw away the document

I have a workaround to accomplish the same thing but it requires more effort and is less user friendly. I have configured a pre and post hook script with POST requests to a third-party application. When I receive the pre hook call and no post hook call within a certain amount of time, the third-party application sends a "document processing failed" message to my phone. I need this custom logic because the post consumption script is not called when the document processing fails.

Unfortunately, this approach is also not error-prone to importing multiple documents at once. When you consume document A and document B at the same time and document B is finished before document A, then this approach notifies success for document A.

I would like to discuss different options with you regarding this topic. I'm also fine if the use case is out of scope, because it is very tailored to me and not useful for other users.

Proposals for discussion

Option 1

• Call the post consumption script for failed documents as well
• Indicate the status of the consumption in a new variable passed to the script
• Provide the error message as argument?

Option 2

• Introduce the environment variable PAPERLESS_FAILED_CONSUME_SCRIPT (name for discussion) with the error message as argument to the provided script

Option 3

• Let users configure a web hook address via a environment variable like PAPERLESS_NOTIFICATION_WEBHOOK (name for discussion):

PAPERLESS_NOTIFICATION_WEBHOOK=http://third-party-service/<unique-webhook-id>

• When the variable is given the document processing notifications will be send via a POST request to the configured web hook. We can also send additional information in a JSON body. For example:

{
  "id": "1" // allows to distinguish the different message types (fail, success, ..(
  "message": "Document successfully imported"
  "" // additional fields depending on the notification id 
}

Option 4

• Add PAPERLESS_IMPORT_FAILED_WEBHOOK and PAPERLESS_IMPORT_SUCCESS_WEBHOOK
• The request to PAPERLESS_IMPORT_SUCCESS_WEBHOOK provides the same arguments as passed to the post consumption script in a JSON body
• The request to PAPERLESS_IMPORT_FAILED_WEBHOOK provides the document name and error message in the JSON body

Option 5

• Like option 4 but only add PAPERLESS_IMPORT_FAILED_WEBHOOK since it delivers the most important information

My current workaround (for anyone interested)

Pre-consumption script

#!/usr/bin/env bash
echo Begin pre-processing script
echo - Original filename: [${1}]
curl -X POST http://<ha-ip>:8123/api/webhook/paperless_start_processing -d "{\"filename\": \"${1}\"}" -H "Content-Type:application/json"
echo End pre-processing script

Post-consumption script

#!/usr/bin/env bash
echo Begin post-processing script
echo - Document id:    [${1}]
echo - Generated filename: [${2}]
echo - Source path:    [${3}]
echo - Thumbnail path: [${4}]
echo - Download URL:   [${5}]
echo - Thumbnail URL:  [${6}]
echo - Correspondent:  [${7}]
echo - Tags:           [${8}]
curl -X POST http://<ha-ip>:8123/api/webhook/paperless_finish_processing -d "{\"filename\": \"${2}\", \"correspondent\": \"${7}\", \"tags\": \"${8}\"}" -H "Content-Type:application/json"
echo End post-processing script

Home Assistant automation

- alias: 'Job - Paperless Process document'
  initial_state: true
  trigger:
    platform: webhook
    webhook_id: paperless_start_processing
  action:
    - variables:
        document: "{{ trigger.json.filename }}"
    - wait_for_trigger:
      - platform: webhook
        webhook_id: paperless_finish_processing
      timeout: '00:10:00'
    - choose:
      - conditions:
          # No trigger happened before timeout expired
          - condition: template
            value_template: "{{ wait.trigger == None }}"
        sequence:
          - service: notify.telegram
            data_template:
              title: 'Job - Paperless Import failed ❌'
              message: |
                - Import failed for document "{{ document }}"
      default:
        - service: notify.telegram
          data_template:
            title: 'Job - Paperless Import successful ✅'
            message: |
                - Original name: "{{ document }}"
                - Import name: {{ wait.trigger.json.filename }}
                - From: {{ wait.trigger.json.correspondent }}
                - Tags: {{ wait.trigger.json.tags }}