Webhooks for SaaS Integrations: How They Work and How to Implement Them

What webhooks are, when to use them instead of polling, and how to build a receiver that stays reliable across many connected customers.

5 min read

On this page

An integration that only reads data when someone asks for it will always be slightly out of date. If a customer updates a deal in their CRM, pays an invoice in their accounting tool or cancels a meeting in their calendar, your product only finds out the next time it checks.

Webhooks change that. Instead of your application repeatedly asking "has anything changed?", the provider tells you when something happens.

This guide explains how webhooks work, how they differ from polling, and what a production webhook receiver needs to handle when it serves many customers at once.

What is a webhook?#

A webhook is an HTTP request that one system sends to another when an event occurs.

You give the provider a URL. When a relevant event happens, such as a contact being created or an invoice being updated, the provider sends an HTTP POST request to that URL with a payload describing the event.

From your application's point of view, a webhook is an incoming API call that you did not initiate. That one fact explains most of the engineering work: you don't control when it arrives, how often, in what order, or whether it arrives at all.

Webhooks vs polling#

Polling means calling the provider's API on a schedule to look for changes. Webhooks mean the provider calls you.

	Polling	Webhooks
Who initiates	Your application	The provider
Freshness	Limited by the polling interval	Close to real time
API usage	Requests are made even when nothing changed	Requests arrive only when something happens
Missed changes	Unlikely if you track a cursor or timestamp	Possible if deliveries fail or are dropped
Infrastructure	Scheduler and API client	Public endpoint, verification, queueing

Most reliable integrations use both. Webhooks provide timely notification, and a periodic reconciliation job catches anything that was missed.

How a webhook integration works#

The lifecycle usually has four parts.

Registration. Your application registers a callback URL with the provider and chooses which events to receive. Some providers configure this once per developer application; others create subscriptions per connected account through an API.

Delivery. When an event occurs, the provider sends a request to your URL. The payload may contain the full record, a partial record, or only an identifier and an event type.

Verification. Your receiver confirms the request genuinely came from the provider. Common mechanisms include an HMAC signature computed with a shared secret, a verification token, or a challenge request during setup.

Processing. Your application interprets the event, often fetches the latest version of the record through the provider's API, and updates its own data.

Acknowledge quickly, then process in the background. Retries handle temporary failures without blocking new deliveries.

Designing a reliable webhook receiver#

Respond quickly#

Many providers expect a successful response within a few seconds and treat slow responses as failures. A receiver should verify the request, store or enqueue the event, and return a 2xx response. Business logic belongs in a background worker.

Verify every request#

Your endpoint is public. Anyone can send a request to it. Check the provider's signature or token on every delivery before trusting the payload, and reject requests that fail verification.

When a provider signs the raw request body, compute the signature over the exact bytes you received. Parsing and re-serializing JSON first can change the bytes and break verification.

Expect duplicates#

Providers commonly deliver events "at least once". The same event may arrive twice, especially after a timeout or retry. Record an event identifier, or a combination of record ID and timestamp, and skip events you've already processed.

Don't rely on order#

Events can arrive out of sequence. An "updated" event may be processed before the "created" event for the same record. Fetching the current state of the record from the API, rather than applying each payload as a change, avoids many ordering bugs.

Treat the payload as a hint#

Some payloads are deliberately thin and only say that something changed. Even when the full record is included, it reflects the moment the event was generated. Retrieving the latest record keeps your data consistent.

Reconcile periodically#

Deliveries fail. Endpoints go down during deployments. Providers disable subscriptions after repeated errors. A scheduled job that compares recent changes against your data, using a change feed or modified-since query where the API offers one, closes the gap.

Webhooks in a multi-tenant SaaS product#

A single receiver usually handles events for every connected customer. Each event has to be routed to the right tenant.

Providers identify the source account in different ways: a company or realm ID in the payload, a subscription ID you created, or a separate callback URL per connection. Your application needs a reliable mapping from that identifier to the internal customer and connection that owns it.

That mapping also determines which credentials to use when you fetch the latest record. An event for Customer A must be processed with Customer A's authorization and never with another customer's token.

Route each event to the customer and connection that own it, and use only that connection's credentials.

Managing webhook subscriptions#

Where subscriptions are created per connected account, they have their own lifecycle:

Create the subscription when a customer connects, and store its identifier.
Renew subscriptions that expire. Some providers require periodic renewal.
Remove subscriptions when a customer disconnects or your product no longer needs the events.
Monitor subscription health, because a provider may silently stop delivering after errors or a revoked authorization.

Subscription management is easy to overlook in a prototype and becomes a support issue at scale.

Security checklist#

Serve the endpoint over HTTPS only.
Verify signatures or tokens on every request.
Use constant-time comparison when checking signatures.
Keep webhook secrets out of source control and logs.
Limit payload size and reject unexpected content types.
Avoid logging full payloads if they contain personal or financial data.
Rotate secrets when the provider supports it, and plan for overlapping validity during rotation.

Where Pathfix fits#

Webhook processing sits next to authorization. To act on most events you need to call the provider's API on behalf of the right customer, which means having valid credentials for that connection.

Pathfix OAuth handles authorization, token storage, refresh and authenticated API passthrough across 350+ providers, so the API lookup after an event can be made with the customer's current credentials. Your application still owns the receiver logic and what it does with the data.

Pathfix Automation can listen for supported changes in individual users' connected accounts and run a configured workflow in that user's context. Webhook availability and supported events vary by provider.

Frequently asked questions#

Are webhooks real time?#

Usually close to it, but not guaranteed. Providers may batch events or delay deliveries, so design for "soon" rather than "instantly".

What happens if my endpoint is down?#

Many providers retry for a period of time, then give up or disable the subscription. Check each provider's retry policy, and use reconciliation to recover missed changes.

Should I use webhooks or polling?#

Use webhooks where the provider supports the events you need, and keep a lightweight reconciliation process. Polling alone is reasonable when a provider has no webhooks or when near-real-time updates don't matter.