You already know one way to start work: the clock. In Class 26, cron woke a job at a planned time — refresh the data at market close, clean up expired rows nightly, send the weekly digest on Monday. The job ran whether or not anything new had happened in the world.

A webhook is the other way to start work: something happened. A visitor submitted a form. A payment completed. A repository received a push. A data provider issued an alert. Instead of your app asking "anything new?" every five minutes, the other service knocks on your door and tells you now.

That is the doorbell metaphor, and it is worth keeping. Polling is a constant phone call — "are we there yet? are we there yet?" A webhook is a doorbell — silence until the visitor arrives, then one ring at the right moment.

The definition

A webhook is an HTTP request another service sends your application when an event happens.

Read that slowly, because every word earns its place:

• Another service is the sender. Your app did not cause this; it is being informed.
• Sends means the direction is inbound. The outside world calls you, not the reverse.
• Your application means you own a receiving URL — an endpoint — that listens for these knocks.
• When an event happens means the trigger is an occurrence in the world, not a time on your schedule.

Concretely: Service A observes an event, then makes an HTTP POST to a URL that Service B owns. B's endpoint receives the request, checks it, records what matters, and starts whatever should follow.

The full path, end to end

A webhook is never just "a POST arrives." The useful pipeline has five stages:

Event in the world
  (payment completed / form submitted / repo push / provider alert)
  → webhook endpoint (your narrow receiving URL)
  → verify (is this real? is it complete?)
  → record / queue (save the fact, schedule follow-up work)
  → visible result (status page, notification, updated record)

Walk it with a real shape. A payment provider observes "checkout completed." It POSTs a JSON payload to yourapp.com/webhooks/payments. Your endpoint verifies the request, writes one row — event ID, type, timestamp — into the database, enqueues a fulfillment job, and immediately answers "received." Later, a worker does the slow work: generating the receipt, updating inventory, sending confirmation. The user sees the result; the browser never waited for any of it.

The same pattern covers the other three classic sources:

• Form submitted: a form service tells your app a visitor sent input. You record the submission and queue a review task.
• Repository push: a code host tells your deployment platform new commits landed. It starts checks and a preview build.
• Data-provider alert: a source tells your app a dataset changed. You record the notice and queue a refresh.

Notice the middle step every time: verify, then record or queue. The endpoint itself does almost no heavy work. It takes the message, confirms it, saves the fact, and hands off. Heavy work belongs in a worker, exactly as Class 26 taught.

A ByeBuy example: the directory submission

Make it concrete with a ByeBuy-style workflow you already understand. A visitor finds a useful data source and submits it to the ByeBuy directory through a form.

Without a webhook, you have two bad options: make the visitor's browser wait while your app validates the URL, checks for duplicates, scores the source, and notifies a reviewer — or poll the form service every few minutes asking "any submissions yet?"

With a webhook, the flow is clean:

1. The visitor submits the form. The form service immediately POSTs a source.submitted event to your endpoint. 2. Your endpoint verifies the request and writes one record: submission ID, submitter, URL, timestamp, status pending_review. 3. Your endpoint enqueues a review job and answers the sender with a fast acknowledgement. 4. A worker later fetches the URL, runs the source-quality checks from Class 19, and updates the record. 5. The visitor sees "received — under review." The reviewer sees a queue. Nobody's browser waited for the slow steps.

The browser did its job in seconds. The system did its job over minutes. The webhook was the hinge between them.

What is inside the payload?

A webhook payload is structured event detail — usually JSON — and a well-designed one carries at least four things:

• Event type: what happened (source.submitted, payment.completed, push.received). This tells your app which handler should run.
• Event ID: a stable unique identifier for this occurrence. You will need it in Lesson 27.3 to survive retries and duplicates.
• Timestamp: when the sender observed the event. You will need it to order events and to notice stale replays.
• Signature: a verification value the sender computed, covered fully in Lesson 27.3. Treat it as "present in serious systems" for now.

Plus the event data itself: the form fields, the payment amount and currency, the commit SHAs, the dataset name. Enough for your app to record the fact and decide what follows — nothing more.

The correction that matters

New builders often hear "the payment service notifies my app" and imagine they handed the payment company the keys to their database. They did not — or they should not have.

That endpoint can do exactly one thing: accept a shaped event, check it, and record it. It cannot run arbitrary queries. It cannot read other tables. It cannot change secrets. It is a mail slot, not an open door. Lesson 27.3 builds the lock for that mail slot — signature verification, fast acknowledgement, duplicate handling — but internalize the boundary now: narrow endpoint, bounded job, everything else stays behind your own authentication.

Check your understanding

1. In your own words, what is the difference between cron waking work and a webhook waking work? 2. Name the five stages between an outside event and a visible result. 3. Why should the endpoint record and enqueue rather than doing the slow work itself? 4. What four fields should you expect in a serious webhook payload?

Exercise: plan one event

Create a file called WEBHOOK-PLAN.md for one real or imagined product event. Keep it to a single event — one doorbell, one job.

# WEBHOOK-PLAN.md — [product name]

## Event
- Source service:
- Event name / type:
- What happened in the world to cause it:

## Receiving URL role
- Endpoint path (e.g., /webhooks/submissions):
- The one job this endpoint is allowed to do:

## Data expected
- Event type field:
- Event ID field:
- Timestamp field:
- Signature field (name per provider docs):
- Event data fields needed for the first record:

## First database record
- Table / record created on receipt:
- Fields written immediately:
- Initial status value:

## Follow-up job (if any)
- Queued work (or "none — record is the result"):
- Worker action:
- User-visible result:

Finish line: one filled-in WEBHOOK-PLAN.md describing a single event from source through endpoint to first record and follow-up.

Verification: hand the plan to a reviewer and ask: "what wakes this work — time or an event — and what is the first row written?" If they can answer both, the plan is sound. If the endpoint description includes anything beyond receive-verify-record-enqueue, narrow it.

Next, Lesson 27.2 gives you the decision rule: for any given event, should you use a webhook, poll on an interval, or run on your own cron schedule? The doorbell is wonderful — when the building has one.