Basehook

A webhook management system that groups updates by thread ID and lets you consume them either one-by-one or buffered (latest revision only).

Core Concepts

Thread-based grouping: Webhooks are grouped by thread ID. Configure JSON paths to extract thread IDs and revision numbers from any format (Slack, GitHub, Shopify, etc.).

Two consumption modes:

• pop(only_last_revision=False) - Process updates one by one in order
• pop(only_last_revision=True) - Buffer updates and only consume the latest revision, skipping outdated ones

Pull-based processing: Your application pulls updates via pop() instead of receiving direct webhook POSTs. Failed processing is marked as ERROR and visible in the UI for manual retry.

Quick Deploy

Docker Compose (Self-hosting)

git clone https://github.com/mehdigmira/basehook.git
cd basehook
docker-compose up -d

Access at http://localhost:8000

Railway (Cloud)

One-click deploy with PostgreSQL auto-configured.

Usage

1. Configure webhook

Visit the UI and create a webhook with thread ID and revision number paths.

2. Install client library

pip install basehook

3. Consume updates

from basehook import Basehook

basehook = Basehook(database_url="postgresql+asyncpg://...")

# Process updates one by one (in order)
async with basehook.pop("webhook-name", only_last_revision=False) as update:
    if update:
        process(update)

# Or buffer updates and only process latest revision
async with basehook.pop("webhook-name", only_last_revision=True) as update:
    if update:
        process(update)  # Older revisions automatically skipped

License

MIT