jscom-notion-counter-service

Overview

A serverless webhook service that automatically increments numeric counters in Notion database pages. Originally built to track how many times items in a lending library database were borrowed, but designed to work with any Notion database where you need to count events or actions.

The service receives webhook notifications from Notion (or any external source), parses the page data, and increments a specified numeric property on the page. It's particularly useful for tracking usage metrics, event counts, or any scenario where you need to maintain a running tally in your Notion workspace.

How It Works

Architecture

The service runs on AWS serverless infrastructure:

API Gateway - Receives incoming webhook POST requests at /v1/notion/counter
Lambda Function - Processes the webhook payload and updates the Notion page
Notion API - Authenticates and updates the target page's numeric property

Webhook Flow

Notion Webhook → API Gateway → Lambda → Notion API → Page Updated

When a configured event occurs in Notion (such as a date field changing), the webhook sends a payload containing the page data to the service. The Lambda function:

Extracts authentication and configuration from request headers
Parses the webhook payload to get the page ID and current property values
Calculates the new counter value (existing value + 1, or 1 if null)
Updates the Notion page via the Notion API

Smart Date Handling

The service includes optional logic to handle date field changes intelligently. When configured with a lent-date-property header, it can detect when a date was cleared (e.g., an item was returned) versus when a date was set (e.g., an item was lent out). This prevents incrementing the counter when an item is returned—only when it's lent out.

Usage

Prerequisites

Notion Integration: Create a Notion integration and obtain an API token
Page Access: Share your target Notion database/page with the integration
Webhook Setup: Configure a Notion webhook for the events you want to track

Webhook Configuration

Configure your webhook to send POST requests to:

https://api.johnsosoka.com/v1/notion/counter

Required Headers

Header	Description	Required
`notion-token`	Your Notion integration token	Yes
`counter-property`	The name of the numeric property to increment	Yes
`lent-date-property`	Property name for date-clear filtering (optional)	No

Example Webhook Payload

The service expects a standard Notion webhook payload:

{
  "data": {
    "id": "page-uuid-here",
    "properties": {
      "Times Lent": {
        "number": 3
      },
      "Lent On": {
        "date": {
          "start": "2024-01-15"
        }
      }
    }
  }
}

Use Case: Lending Library

The original use case tracks items in a lending library:

Database has items with a "Times Lent" counter and "Lent On" date
When "Lent On" is set (item borrowed), webhook triggers
Service increments "Times Lent" by 1
When "Lent On" is cleared (item returned), service skips processing
Result: Accurate count of total lend events per item

Deployment

The service is deployed using Terraform:

cd terraform
terraform init
terraform apply

Infrastructure includes:

Lambda function with Python 3.12 runtime
API Gateway route and integration
IAM permissions for CloudWatch logging