API and Webhooks Explained for Agencies and Integrators
A client's storefront shows a paid order, but the CRM has no matching purchase and fulfilment hasn't started. The endpoint is reachable, the integration dashboard looks healthy, and someone suggests replaying the notification. Without a delivery contract, that replay could fix the missing record or create a duplicate shipment.
APIs and webhooks need to be designed together, with recoverability ahead of apparent speed. For agencies moving into larger projects and integrators replacing maintenance-heavy platforms, the important question isn't whether systems can exchange requests. It's whether the team can prove what happened, repair failures safely, and hand over an integration that doesn't depend on its original developer.
Table of Contents
- APIs and Webhooks Side by Side
- Polling Versus Webhooks for Event Updates
- Following One Order Through an API and a Webhook
- Handling Duplicates, Retries and Missed Events
- Securing Webhook Endpoints Against SSRF Attacks
- Monitoring Delivery Before Clients Notice Gaps
- Confirm Your Integration Contract Before Go-Live
APIs and Webhooks Side by Side
Fetch an order by ID and the caller chooses the moment, the question and the shape of the answer. Subscribe to order.paid and the source chooses the moment, while the receiver only decides whether to accept the delivery. WebinOne exposes APIs and webhooks for these complementary jobs, so the design question is who needs to initiate each exchange.
API versus webhook across the criteria that matter in production
| Criteria | API (request and response) | Webhook (event push) |
|---|---|---|
| Who starts the exchange | The client sends a request | The source system sends an event |
| Trigger | Application code decides when to ask | A state change occurs in the source system |
| Typical use | Read or change a record on demand | Tell another system that something happened |
| Data freshness | As current as the last request | Near real time, once delivered |
| Request volume | Grows with polling frequency | Grows with the number of events |
| Failure handling | The caller retries the request | The sender retries; the receiver deduplicates |
| Security focus | Credentials, scopes and rate limits | Signature checks, timestamp windows and destination controls |
| Example | Fetch an order by ID | POST order.paid to a CRM endpoint |
Both mechanisms ride on ordinary HTTP. The dividing line is request-response access on one side and event-triggered notification on the other, and treating them as competing technologies produces brittle integrations. An API pull answers a question chosen by the caller. A webhook reports that the source already recorded a change.
A CRM integration shows why the split matters in day-to-day work. The webhook fires the moment a payment lands, so fulfilment reacts without waiting for a scheduled check. The API remains the authoritative read when support needs the current order state, or when a missed delivery has to be reconciled against what the source recorded.
For teams aligning technical and commercial stakeholders, VolunteerBadge's REST, webhooks and OAuth explained provides useful terminology for separating resource access, notifications and authorization. Those distinctions belong in the scope of work, not just developer documentation.
Polling Versus Webhooks for Event Updates
WebinOne can push event notifications to subscribed endpoints, allowing receivers to react without waiting for their next scheduled check. Polling remains useful when push isn't available or when a scheduled comparison is the actual business requirement.
Checking a parcel tracker repeatedly is polling. Receiving a text when the parcel is scanned is the push equivalent. The operational difference is who takes responsibility for starting the exchange.
With polling, the receiving application asks for changes on a schedule. Empty results still consume requests, and a change immediately after a check remains undiscovered until the next check. Shortening the interval reduces that delay but increases traffic.
How the notification reaches the receiver
A subscription associates a receiving endpoint with a named event. When the event occurs, the source sends an HTTP POST to that endpoint, and the receiver returns a success status to acknowledge acceptance. This uses ordinary web infrastructure rather than requiring a specialised messaging network.

An analysis of 100 API companies, described by RealtyAPI's webhook integration guide, found that 83% offered webhooks in 2023, increasing to 85% in 2024. That measures provider availability, not whether any particular implementation offers safe replay or complete delivery reporting.
Push also changes the infrastructure requirement. The receiving team must maintain an accessible endpoint and handle bursts, whereas a polling client can initiate outbound requests on its own schedule. The RenderIO polling and webhook guide is a useful companion when assessing that implementation trade-off.
A notification shouldn't be assumed to contain the complete current record. Some carry detailed snapshots; others carry identifiers. The receiving application should use the documented payload contract and retrieve authoritative details through the API when needed.
The vocabulary for the handover should stay precise:
- Event: The recorded business change.
- Subscription: The registration connecting an event to a destination.
- Delivery: An attempt to transmit that notification.
- Acknowledgement: The receiver's confirmation that it accepted the delivery.
Following One Order Through an API and a Webhook
WebinOne provides the platform-side events and API access for a connected order workflow; the integration supplies the receiving, processing and recovery logic. The following scenario uses illustrative event labels, not a promise that those labels match a particular endpoint specification.
The business goal is straightforward: a paid purchase should become a correctly attributed CRM transaction and an actionable fulfilment record. Each system needs an explicit responsibility.

From payment to processing
The storefront records payment and emits a webhook. The customer pays, the platform persists the order's paid state, and an illustrative
order.paidnotification goes to the registered CRM receiver. The persisted order remains the source of truth, so notification delivery isn't the only evidence of the purchase.The receiver accepts responsibility for the event. It checks the signature and timestamp, validates the envelope, and stores the event ID and processing state durably before returning success. Slow CRM and fulfilment operations stay outside the request path, preventing their latency from deciding whether receipt succeeds.
A queued worker retrieves the order through the API. Using the order identifier, it requests the line items, delivery address and current status needed for processing. The REST API endpoint guide supports endpoint planning, but the integration should request only fields required for its business action.
The worker updates the CRM through its API. It creates or updates the contact and purchase association, using the event identifier as an idempotency key where the destination supports one. A separate customer-matching rule prevents a legitimate repeat buyer from becoming another contact merely because a new order arrived.
Fulfilment writes its result through the orders API. After accepting the work, the fulfilment process updates the order's dispatch state or shipment reference. The platform can then emit the relevant update notification, illustrated as
order.updated, so connected storefront views can refresh without treating the update as another payment.A scheduled reconciliation checks the business outcome. The job compares paid orders with CRM purchase associations and fulfilment acceptance records. Missing or inconsistent records become repair tasks, rather than depending on someone noticing an absent notification.
Define the finished state
After reconciliation, the storefront holds the authoritative order and its current fulfilment state. The CRM associates that purchase with the correct customer, and fulfilment holds a traceable job linked to the original order identifier.
“Finished” doesn't mean every system stores an identical copy. It means each system holds the information it owns, with stable references connecting the records.
A successful handover includes evidence of the business result, not just evidence that a POST reached an endpoint.
Handling Duplicates, Retries and Missed Events
For WebinOne integrations, receivers should be designed around at-least-once processing assumptions, without inventing an undocumented platform retry guarantee. The actual sender's retry window, replay facilities and ordering behaviour must be recorded before launch.
A sender can lose the response after a receiver accepts an event. From the sender's perspective, delivery is uncertain; from the receiver's perspective, the work may already exist. Retrying is reasonable, but processing the retry as a new business action isn't.
Google Cloud's retry guidance documents that event-driven functions can execute more than once and recommends combining retries with idempotency. The receiver therefore needs a durable event record, not an in-memory list that disappears during deployment.
Build the event ledger first
Store the source, tenant, event identifier, payload version and processing state under an appropriate uniqueness constraint. A duplicate insert should resolve to the existing record rather than start another worker. Retain enough state to distinguish accepted, processing, completed and failed work.
A blanket “already received” check isn't sufficient. If a worker crashes after receipt but before completion, the event still needs recovery. Claiming work and advancing its state should be transactional where possible.
Webhook failure modes, causes and fixes
| Failure | Likely cause | Fix |
|---|---|---|
| Duplicate event | Sender retried after a timeout or non-success response | Store the event ID under a unique constraint and skip repeats |
| Missed event | Endpoint stayed down past the retry window without a dead-letter queue | Configure a dead-letter queue and reconcile against the source |
| Out-of-order event | Retries or parallel workers changed delivery order | Compare resource versions or trustworthy event timestamps before writing |
| Slow acknowledgement | Business logic runs before the response | Acknowledge after durable acceptance and process from a queue |
| Silent schema change | Provider added, renamed or removed fields | Validate the schema and alert on incompatible or unexpected changes |
| Duplicate side effects | Repeated delivery creates another order, email or CRM record | Use the event ID as the downstream idempotency key |
Bound retries and preserve exhausted work
Use exponential backoff with jitter and explicit limits on attempts and event age. Longer retry windows improve tolerance for outages but can also deliver old work after the business state has changed. Workers must check whether the action is still valid.
For comparison, Amazon EventBridge's FAQ documents a default retry policy of up to 24 hours and 185 attempts, with exhausted events dropped unless a dead-letter queue is configured. Those are service-specific settings, not universal webhook defaults or WebinOne commitments.
Downstream writes need protection too. The retry safety practices from Fetchin are useful when specifying how an uncertain API response can be retried without repeating the mutation. Where a destination lacks idempotency support, use a durable operation ledger and query for the existing result before retrying.
For money-related workflows, the payment processing integration guide provides the relevant implementation context. Payment confirmation, inventory reservation and customer messaging shouldn't become an inseparable transaction inside the receiver.
A slower event that can be replayed and reconciled is safer than an apparently immediate event that disappears during a traffic spike.
Securing Webhook Endpoints Against SSRF Attacks
A WebinOne integration's security design must cover destination validation at registration and delivery, plus isolation of outbound workers. A valid signature authenticates the sender. Destination validation decides where the request can go.
Server-side request forgery, or SSRF, arises when an attacker supplies a destination that causes a server to request a resource on the attacker's behalf. With webhooks, that resource could be an internal service or a cloud metadata endpoint exposing credentials, an attack surface identified in OWASP's API Security Top Ten discussion.
The risk sits on both sides of the contract. Receivers harden their endpoints, yet a perfectly authenticated sending platform can still deliver a legitimate request to a maliciously configured destination.

Control where outbound requests can go
Destination controls should apply to the system that makes the request:
- Validate twice: Check the URL when registered and again before delivery, including hostname resolution.
- Require HTTPS: Reject unsupported schemes rather than attempting to normalise them into something usable.
- Block internal destinations: Exclude loopback, link-local, private and cloud-metadata address ranges, including the 169.254.169.254 instance metadata address that cloud providers expose to running machines.
- Restrict redirects: Disable them or validate every destination in the redirect chain.
- Bound resource use: Enforce connection timeouts, response limits and maximum payload sizes.
- Isolate delivery workers: Prevent webhook workers from reaching privileged network services.
Checking only the original URL leaves gaps when a hostname resolves differently later or a redirect points elsewhere. Network-level egress restrictions provide an additional boundary when application validation fails.
Authenticate the action, not just the sender
Inbound receivers should verify signatures against the original request bytes and enforce the agreed timestamp window. Rotate secrets with an overlap procedure, or use the agreed asymmetric-signature mechanism. Schema validation should happen before business processing.
Authorization needs its own check. A signed event for one client site must not select credentials or mutate records belonging to another tenant. Resolve the source account against a trusted internal mapping rather than trusting a payload-supplied destination account.
Logs should capture request identifiers, timestamps, delivery status, latency and redacted error details. Secrets and unnecessary customer data don't belong in diagnostic output.
Before approval, the implementation owner should document where outbound requests can go, how destinations are validated, and what gets logged. Undocumented controls shouldn't be treated as verified platform capabilities.
Monitoring Delivery Before Clients Notice Gaps
WebinOne reports 99.99% uptime, with a 99.95% availability commitment in its published SLA, but platform availability doesn't prove that a receiver completed its business work. Monitoring must distinguish delivery acceptance from processing completion.
The WebinOne Portal includes a System Status page showing the current status of the platform and its services in one place. A healthy platform status still leaves receiver deployments, expired credentials, stalled workers and rejected downstream writes to investigate.
AWS's event-monitoring guidance recommends tracking InvocationAttempts, SuccessfulInvocationAttempts and RetryInvocationAttempts at the rule level. Equivalent counts should be available for each integration subscription, with accepted events connected to their eventual processing state.
Set alerts around failure behaviour
A useful operational checklist is short:
- Delivery attempts: Compare total attempts with successful deliveries and retries, grouped by subscription.
- Failure rate: Alert above an agreed percentage over a rolling window chosen for the workflow's traffic.
- Dead-letter backlog: Investigate any non-empty queue rather than allowing failed work to become permanent storage.
- Acknowledgement latency: Alert before responses approach the sender's documented timeout.
- Processing completion: Track accepted events that remain unfinished beyond the agreed business deadline.
For a concrete timeout boundary, AWS's API destinations documentation specifies a maximum client execution timeout of 5 seconds. That limit applies to that delivery service; every other sender needs its own recorded timeout.
Structured logs should include the event ID, timestamp, response code, retry count and dead-letter queue depth. Add a business identifier, such as the order reference, so support staff can trace a customer complaint without searching raw payloads.
Make recovery a routine task
A ten-minute weekly review can check the delivery counts, inspect failed work and confirm that reconciliation completed. Operators should fix the cause before replaying dead-letter events, preserve the original event identifiers, and record the repair outcome.
For critical workflows, that review supplements alerts rather than replacing them. Platform reliability and deployment discussions belong with the WebinOne enterprise team, while the integration runbook must name the person responsible for receiver-side recovery.
Confirm Your Integration Contract Before Go-Live
Go-live approval should rest on documented failure behaviour and tested recovery steps. Treat the webhook as a delivery contract between two systems: the sender commits to a retry window and a signature method, the receiver commits to a fast acknowledgement and idempotent handling, and both sets of terms belong in writing before traffic starts.
Systems integrators use WebinOne as the platform layer in enterprise and government projects, which keeps managed platform responsibilities separate from the integration logic and external systems the delivery team still governs. Partner and Agency level users get help directly from the WebinOne Team in Slack when a contract term depends on platform behaviour.
Require an operational handover
The platform documentation guide covers the platform side of the agreement. The project-specific half is the operational handover, which should contain seven items:
- Events and schema versions: Name each event, required fields, compatibility rules and the resource identifiers used for recovery.
- Endpoint ownership: Assign an accountable owner, tenant mapping, approved destination and escalation path.
- Retry and dead-letter policy: Specify the retry window, exhausted-event destination, replay procedure and duplicate-handling rules.
- Signature and rotation method: Record verification requirements, replay protection and the secret rotation schedule.
- Acknowledgement target: Define expected response time and the durable acceptance boundary.
- Reconciliation schedule: Name the source-of-truth comparison, its frequency, repair procedure and owner.
- Decommissioning date: Set the retirement date or review deadline, including subscription removal and credential revocation.
Each item answers a question that otherwise surfaces during an incident. Schema versions decide who handles drift. The retry policy decides how missed work is recovered. Duplicate rules decide whether a replayed event can trigger the same business action twice. Decommissioning decides how a retired destination stops receiving customer information.
Price this work explicitly on larger agency projects. A quote that covers build time alone leaves schema changes, replay handling and reconciliation as unbilled effort, and moving away from patching-heavy delivery improves margins only when integration failures have a named owner and a budgeted maintenance line.