Notification Payloads

This page describes the structure of notification payloads sent by our platform.

Common Payload Structure

All notifications share a common payload structure:

{
  "id": "evt_123456789",
  "event": "EVENT_TYPE",
  "event_level": "LEVEL",
  "team_id": "team_123456",
  "project_id": "proj_123456",
  "upload": {
    // Upload data
  },
  "task": null // or Task data
}

Payload Fields

Field	Type	Description
id	String	Unique identifier for the notification event
event	String	Event type (UPLOAD_IN_REVIEW, UPLOAD_PROCESSED)
event_level	String	Level at which the event occurred (UPLOAD or TASK)
team_id	String	ID of the team that owns the project
project_id	String	ID of the project where the event occurred
upload	Object	Data about the upload
task	Object	Data about the task (null for upload-level events)

Upload Object

The upload object contains information about the upload:

{
  "id": "upl_abcdef123456",
  "name": "invoice.pdf",
  "status": "IN_REVIEW",
  "files": {},
  "meta": [
    {
      "name": "reference",
      "value": "INV-2023-001"
    }
  ],
  "folder_id": "folder_123456",
  "created_at": "2023-06-15T10:30:00Z"
}

Upload Fields

Field	Type	Description
id	String	Unique identifier for the upload
name	String	Name of the upload
status	String	Current status (PROCESSING, COMPLETED, IN_REVIEW)
files	Object	Information about the files in the upload
meta	Array	Array of metadata key-value pairs
folder_id	String	ID of the folder containing the upload
created_at	String	Timestamp when the upload was created

Task Object

For task-level events, the task object contains information about the specific task:

{
  "id": "tsk_123456",
  "status": "COMPLETED",
  "document_type": "invoice",
  "extracted_data": {
    "invoice_number": "INV-2023-001",
    "date": "2023-06-01",
    "total_amount": 1250.0,
    "currency": "USD"
  }
}

Processing Notifications

When receiving notifications:

1. Parse the JSON payload
2. Check the event and event_level to determine the type of notification
3. Extract relevant data from the upload and/or task objects
4. Take appropriate action based on the event type

Best Practices

• Validate the payload structure before processing
• Implement idempotent handling to avoid duplicate processing
• Log notification details for troubleshooting
• Implement proper error handling in your receiving systems