Getting Started

Home · Next: Replay and Idempotency

Requirements

Python 3.12 or newer, Git, and a terminal. Run the app locally with one process.

Windows PowerShell

 git clone https://github.com/DimaGutierrez/webhook-lab.git
 cd webhook-lab
 python -m venv .venv
 .\.venv\Scripts\python.exe -m pip install -r requirements.lock
 .\.venv\Scripts\python.exe -m webhook_lab

Using the virtual environment's executable directly avoids changing PowerShell's execution policy.

macOS / Linux

git clone https://github.com/DimaGutierrez/webhook-lab.git
cd webhook-lab
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.lock
python -m webhook_lab

Unlock the workbench

Open http://127.0.0.1:8000. In a second terminal, from the repository root, read your local token:

• PowerShell: Get-Content data/admin.token
• macOS/Linux: cat data/admin.token

Paste it into the workbench. Keep this token private. The UI holds it only in memory; locking or reloading clears it. If you configured WLAB_ADMIN_TOKEN, use that value instead.

Your first failure-to-recovery story

1. Click Send sample event to send a synthetic POST to the inbox.
2. Select the captured event and inspect its body and sanitized headers.
3. Replay to Demo · unavailable (503) and inspect the failed attempt.
4. Replay the same event to Demo · accepts (200).
5. Confirm both attempts remain in the event history.

The demo destinations are simulated in-process handlers. To exercise an actual HTTP connection, continue to Replay and Idempotency.

Send your own synthetic event

Copy the private inbox URL from the workbench. In PowerShell:

$inbox = 'http://127.0.0.1:8000/in/YOUR_INBOX_TOKEN'
Invoke-RestMethod -Method Post -Uri $inbox -ContentType 'application/json' -Body '{"order_id":"DEMO-001","event":"order.created"}'

In macOS/Linux:

curl -X POST 'http://127.0.0.1:8000/in/YOUR_INBOX_TOKEN' \
  -H 'Content-Type: application/json' \
  --data '{"order_id":"DEMO-001","event":"order.created"}'

Replace the placeholder with your local inbox token. A successful capture returns 201 after persistence. Refresh the workbench to see newly captured events; there is no live feed yet.

Stop and restart

Use Ctrl+C in the app terminal. Events and attempts persist in data/lab.sqlite3. Start again from the same repository directory to reuse the same default data folder.

A Docker alternative is documented in the README; its initial runtime has not been verified in the development environment.

Did the first run work? Share your OS and the first confusing step in the 503 → 200 challenge.