Webhook

A webhook pushes an event

GitHub's webhook overview describes notifications delivered to an external web server when selected events occur. A sender may post an authorization status change, completed appointment, payment event, document update, or failed job to a receiver's HTTPS endpoint.

An API is a broader interface that software can call. Polling asks the API for current state on a schedule. A webhook pushes a message after an event. Many reliable integrations use both: the webhook provides a prompt, and the receiver calls the authoritative API to confirm current state.

Receiving an HTTP request proves only that a request arrived. It does not prove the sender was authentic, the event was new, the payload was valid, or the intended business action finished.

Define an event contract

For every subscription, record:

• sender, receiver, environment, endpoint, and owner
• event name, trigger, payload schema, and version
• stable event or delivery identifier
• authoritative object identifier and source of truth
• authentication and signature method
• timestamp, replay window, and ordering rules
• retry schedule, timeout, and terminal-failure behavior
• data classification, retention, and logging limits
• downstream action, human approval, and reconciliation

Version the contract. A field can be added, removed, renamed, or reinterpreted. Test unknown fields and older versions without silently dropping the event.

Verify before processing

The GitHub best-practices page recommends subscribing only to needed events, using HTTPS, using a webhook secret, checking event type and action, redelivering missed events, and using a delivery identifier. These details apply to GitHub's product, while the control pattern is broadly useful.

The signature-validation guide explains how its HMAC-based signature lets a receiver check source and payload integrity. Follow the actual sender's algorithm. Verify the raw request before parsing or transforming it, compare safely, store secrets outside code, rotate them, and support a controlled overlap period when needed.

An IP allowlist can add a layer when the sender publishes stable ranges. It should not replace signature or authentication checks.

Treat delivery as at-least-once unless proven otherwise

Senders may retry after a timeout or lost response. The first request may have succeeded even when the acknowledgment never arrived. Use a stable event or delivery ID and an idempotent business action so the same event can be processed twice without creating two claims, refunds, appointments, or messages.

Events can arrive late or out of order. Compare event version, source timestamp, sequence, and current authoritative state before applying a change. A “canceled” event followed by an older “scheduled” event should not reopen an appointment.

Respond quickly after authentication and durable receipt, then process through a queue where appropriate. Maintain retry limits, backoff, an exception queue or dead-letter path, replay tools, and an owner for stuck events.

Limit PHI and vendor access

Send identifiers and fields needed for the event's purpose. Avoid secrets or sensitive information in the endpoint URL. Redact or restrict payloads in application logs, monitoring, screenshots, and support tickets.

The HHS business-associate guidance explains that a vendor creating, receiving, maintaining, or transmitting PHI on behalf of a covered entity or business associate may be a business associate, and that required assurances are documented through the applicable agreement. Classify each relationship and data flow. A BAA does not replace permissible-use, security, minimum-necessary where applicable, or state-law analysis.

Use the NIST Cybersecurity Framework to place the integration within governance, asset inventory, protection, detection, response, and recovery work. Include the endpoint, secret, queue, logs, vendor, and dependencies in risk review.

A fictional authorization webhook

Bright Harbor ABA receives 50 deliveries during a test window. Three are valid redeliveries of earlier events, leaving 47 unique events. The receiver applies 45 and routes two to an exception queue because the source version is unknown.

Unique-event processing is 45 of 47, or 95.7%. Exception routing is 2 of 47, or 4.3%. Delivery volume remains 50 for infrastructure monitoring, while business processing uses the 47-event denominator.

One applied event says an authorization changed to approved. Staff confirm the member, payer, product, service, dates, provider, location, units, and source before releasing a schedule. The webhook is evidence of a status message, not a payment promise.

Monitor end-to-end outcomes

Track signature failures, invalid schemas, duplicate deliveries, unique events, queue age, retries, terminal failures, and business actions reconciled to the authoritative source. Define the measurement window and denominator.

Useful measures include authenticated deliveries divided by deliveries received; unique events completed or exception-queued divided by unique events due; and business actions reconciled divided by actions created. Report missing expected events separately because a received-event denominator cannot expose events that never arrived.

Test secret rotation, sender outage, receiver outage, replay, duplicates, delayed events, reversed order, new fields, retired fields, and queue recovery. Record who can disable the endpoint, replay events, approve a schema version, and resume processing.