Webhook

How webhooks work

A webhook flips the direction of an integration. With a normal API call, the client asks and the server answers. With a webhook, the client registers a URL once and the server calls that URL whenever a subscribed event fires. GitHub frames it as expressing interest in an event once, when the webhook is created, and then receiving data as it happens rather than polling an API to see whether data is available 1.

A working webhook has four parts.

• An event. Something in the source system changes state, such as a job finishing or a payment clearing.
• A subscription. The receiver registers an HTTPS endpoint and picks the events it wants.
• A delivery. The source sends an HTTP request, usually a POST with a JSON body that describes the event.
• An acknowledgement. The receiver answers with a success status so the sender marks the delivery as done.

Production trouble often starts at the acknowledgement. Stripe tells receivers to return a successful status quickly, before any complex logic that might cause a timeout, and to process events through an asynchronous queue 2. A handler that writes to the CRM, calls three other services and only then replies will eventually time out. The sender then retries an event the handler already half processed.

Retries are part of the contract. In live mode, Stripe keeps attempting delivery for up to three days with exponential back off 2. The same documentation warns that an endpoint can receive the same event more than once and that events are not guaranteed to arrive in the order they were generated 2. Build the receiver for repeats and reordering from the first day.

A webhook URL is reachable from the internet, so anyone who finds it can post to it. Stripe signs every event in a Stripe-Signature header and needs the raw request body for verification, because any change to the body makes the check fail 2. Without verification, an attacker could send fake events that grant access or modify records 2.

In data work, webhooks usually report on long jobs. A data enrichment run over thousands of rows can take minutes, so the provider accepts the job, returns an ID and calls back when results are ready. RichAPI follows that pattern for bulk email work. Its email_finding and email_verification endpoints accept arrays and run as jobs, and the client either polls a free inquiry endpoint or registers a webhook 3.

What to get right before a webhook goes live

Six decisions determine whether a webhook stays reliable after launch.

**Verify every delivery.** Check the signature against the raw body before parsing JSON or touching a database. Stripe documents this for its events, and RichAPI signs its job webhooks with HMAC for the same reason 23. Reject anything that fails and log the attempt.

**Acknowledge first, work later.** Return a success status as soon as the event is stored. Move enrichment, CRM writes and notifications to a queue that a worker drains at its own pace 2.

**Make handlers idempotent.** Record each event ID and skip events already processed 2. For a waterfall enrichment job, that means a repeated job notice does not write the same email twice or start a second run.

**Do not rely on order.** Store the event time or the object state and reconcile against it 2. If a completion event lands before a started event, the handler should still end in the right state.

**Keep a polling fallback.** Deliveries fail when endpoints go down, certificates expire or firewall rules change. A scheduled check for stuck work catches what a missed delivery leaves behind. On RichAPI bulk email jobs, that check can use the free inquiry endpoint 3.

**Rotate secrets with overlap.** Stripe can keep an old endpoint secret valid for up to 24 hours after a roll, so verification code can be updated without dropped events 2. Plan the same window for any signing secret.

Treat the receiving endpoint as production infrastructure. It needs an owner, monitoring and an alert when deliveries start failing, like any service that writes to customer records.

Example of a webhook closing out a bulk email finding job

A RevOps engineer has a conference list with first name, last name and company domain for each attendee. Calling email_finder once per row from a spreadsheet script would mean tracking a separate request for every attendee. The team submits the list as one bulk email_finding job and registers a webhook for the job 3.

Step 1   POST the list to email_finding and store the job ID
Step 2   Mark the job as submitted in the run table
Step 3   Receiver gets a signed job delivery
Step 4   Verify the HMAC signature against the raw body
Step 5   Return 200, enqueue the job ID, stop
Step 6   Worker reads results, writes hits, tags misses
Step 7   Nightly check polls inquiry for jobs still open

The receiver does almost nothing inside the request. It checks the signature, stores the event and answers, which keeps it well inside a sender timeout 23. The worker does the heavy part afterward.

Billing follows the published rules. Email lookups that find nothing return billed false and cost nothing, and email_finder lists 5 credits per call 3. The job owner can forecast spend from the expected hit rate rather than from list size.

If the same job notice arrives twice, the worker sees a job ID it already processed and skips it 2. If the receiver is down during a deploy, the nightly check polls the free inquiry endpoint for any job still marked submitted 3. A missed delivery then delays results instead of losing them.

Hits flow into the CRM, where match rate is measured against the rows submitted. Misses wait for a later pass instead of a tight retry loop. The same pattern suits an AI agent that starts a long job and should not sit on an open connection while it runs.

Webhook vs polling

Both keep two systems in sync. A webhook pushes a delivery when an event happens. Polling has the client call an API on a schedule to ask whether anything changed 1.