Webhooks and APIs solve different timing problems. An API request starts when your application decides to ask or act. A webhook starts when another system decides an event has happened. Reliable integrations often need both, joined by explicit identity, retry, and reconciliation rules.
This page owns the webhook-versus-API selection decision, including the reverse wording “API vs webhook.” The REST API guide owns designing and exposing an API contract; this page uses only a minimal request-response fixture. A future webhook examples guide will own provider-neutral receiver implementation, signing fixtures, and runnable code. This page shows only the controls needed to make the architecture choice. Webhook versus WebSocket is a separate decision about callbacks versus a persistent bidirectional connection and is not evaluated here.
Direct answer
What is the difference between a webhook and an API?
Use an API call when your application needs to request data or an action and receive a response now. Use a webhook when another system should notify your application after an event. They are not opposites: a webhook is usually an HTTP callback, and dependable integrations often use webhooks for timely signals plus API calls for commands, current-state reads, and reconciliation.
One exchange starts with a request. The other starts with an event.
Both mechanisms usually travel over HTTP, but the owner of time changes. That difference determines the user experience, network boundary, retry responsibility, and recovery model.
Exchange map
Follow who starts, then follow how state recovers
API request and response
The caller chooses when to exchange data and can branch on the response now.
Webhook callback and worker
The provider chooses when to notify; your app owns authentication, durable work, and repair.
Deterministic conceptual diagram. It shows message ownership, not measured latency or a live provider integration.
API request and response
- Best when
- Your application knows when it needs a read or command and needs an immediate success, failure, or accepted response.
- Watch for
- Timeouts can leave a mutation outcome ambiguous. Rate limits, stale reads, pagination, response validation, and retry safety remain your responsibility.
- Operating rule
- The caller owns the schedule, timeout, retry budget, and interpretation of the response.
Webhook event callback
- Best when
- Another system knows when a meaningful event happened and your application should react without constant polling.
- Watch for
- Delivery can be duplicated, delayed, retried, or out of order. The receiver needs authentication, durable event identity, bounded acknowledgement, and recovery.
- Operating rule
- The sender owns the delivery attempt; the receiver owns validation, durable claiming, processing, and reconciliation.
Webhook signal plus API reconciliation
- Best when
- You need prompt event notification and a dependable way to retrieve current authoritative state or repair a missed sequence.
- Watch for
- Two paths create more state transitions. Decide whether the event payload is authoritative, a snapshot, or only a signal to fetch current state.
- Operating rule
- Use the webhook to wake the workflow and the API to command, confirm, or reconcile it.
Webhook vs API across eight production decisions
Do not choose from a feature checklist. Choose from the timing, state, and failure contract your workflow actually needs. The linked citations establish the underlying transport or provider behavior; the decision rules are editorial analysis.
| Decision | API request | Webhook callback | Rule |
|---|---|---|---|
| Who starts the exchange? [1]IETF RFC 9110: HTTP Semantics [3]GitHub Docs: Best practices for using webhooks [4]Stripe Docs: Receive events at your webhook endpoint | Your application sends a request when a user action, schedule, or workflow needs data or a command. | The provider sends a callback because an event occurred, using an endpoint your application exposed in advance. | If your system knows when to ask, start with an API. If the provider alone knows when something changed, add a webhook. |
| Do you need an answer in the current interaction? [1]IETF RFC 9110: HTTP Semantics [3]GitHub Docs: Best practices for using webhooks [4]Stripe Docs: Receive events at your webhook endpoint | The response can return current data, validation errors, authorization failure, or an accepted operation identifier. | The callback normally acknowledges delivery. It should not be treated as the original user interaction waiting for a business result. | Use request-response for immediate decisions. Use a webhook to continue work after the initiating interaction has ended. |
| How fresh must the state be? [1]IETF RFC 9110: HTTP Semantics [4]Stripe Docs: Receive events at your webhook endpoint | A read retrieves the provider state at the time of the request, subject to its documented consistency and caching behavior. | A callback reduces polling delay, but network queues and retries mean arrival time is not the same as event time. | Do not call webhooks “real time” without a measured provider guarantee. Store event time, delivery time, and processed time separately. |
| Can your application accept inbound traffic? [3]GitHub Docs: Best practices for using webhooks [4]Stripe Docs: Receive events at your webhook endpoint | Only the client needs to reach the provider endpoint. This can work from jobs or private systems with outbound access. | The provider must reach a stable public HTTPS endpoint, and the receiver must stay available through deploys and incidents. | If a safe inbound endpoint is impossible, poll an API deliberately. Do not expose an unprotected callback merely to avoid polling. |
| What does a retry mean? [1]IETF RFC 9110: HTTP Semantics [3]GitHub Docs: Best practices for using webhooks [4]Stripe Docs: Receive events at your webhook endpoint | A timed-out read is usually repeatable. A timed-out mutation can be ambiguous unless the operation has an application-defined idempotency contract. | The sender may deliver the same event again. The receiver must recognize a completed duplicate without repeating the business effect. | Define identity, payload fingerprint, concurrent first-write behavior, retention, conflict response, and downstream reconciliation before retrying a side effect. |
| How do you recover missing or out-of-order state? [4]Stripe Docs: Receive events at your webhook endpoint | A list, detail, or changed-since endpoint can rebuild current state when the provider exposes one. | The event stream may be delayed or out of order, and provider retention or redelivery windows vary. | Keep a cursor or reconciliation checkpoint. Use an API read to repair state when event order alone cannot prove the current truth. |
| What authenticates the exchange? [2]IETF RFC 2104: HMAC [3]GitHub Docs: Best practices for using webhooks [4]Stripe Docs: Receive events at your webhook endpoint | The caller usually presents a server-side API key, scoped token, OAuth grant, or another provider-defined credential. | The receiver validates a provider-defined secret or signature over the exact required message bytes, then applies separate business authorization. | Authentication proves the caller or delivery path, not permission to read or change an arbitrary business record. |
| What must operations observe? [3]GitHub Docs: Best practices for using webhooks [4]Stripe Docs: Receive events at your webhook endpoint | Track request count, status, latency, timeouts, rate limits, retry attempts, and provider request identifiers. | Track accepted, rejected, duplicate, pending, completed, failed, and replayed events plus acknowledgement and processing latency. | A 2xx callback proves acknowledgement, not that the business effect completed. Observe delivery and processing as separate states. |
The most common production answer is not “webhook or API.” It is “webhook for notification, API for command and repair.” The important work is defining which path may change durable state and how the other path catches up.
Three minimal fixtures make the timing difference visible
These transcripts use reserved .test domains and fictional identifiers. They teach the exchange shape without inventing a provider or presenting generic signature fields as a universal standard.
Minimal fixture 01
API: your application asks for current state
The caller decides when it needs the order. The HTTP status and versioned response are available in the same exchange, so the workflow can branch immediately.
GET /v1/orders/order_123 HTTP/1.1
Host: api.example.test
Authorization: Bearer ${API_TOKEN}
Accept: application/json
HTTP/1.1 200 OK
Content-Type: application/json
{"id":"order_123","status":"paid","version":7}Fixture boundary: This reserved-domain transcript is illustrative, not a live provider call. API_TOKEN is a placeholder for a server-side credential. A real integration must follow the provider contract, scopes, versioning, rate limits, and error model.
Minimal fixture 02
Webhook: the provider announces an event
The provider chooses when to send the callback. The receiver authenticates the exact delivery, durably claims its identity, queues work, and acknowledges without pretending the downstream effect already completed.
POST /webhooks/provider HTTP/1.1
Host: app.example.test
Content-Type: application/json
X-Event-ID: evt_123
X-Signature: t=1721347200,v1=<computed-hmac>
{"type":"order.paid","data":{"id":"order_123","version":7}}
<provider-defined acknowledgement status and body>Fixture boundary: This is a generic message shape, not drop-in signature code. Header names, canonical bytes, timestamps, algorithms, response deadlines, retry schedules, and event identity are provider-specific.
Minimal control flow
Authenticate, store event and outbox, then acknowledge
The exact provider library belongs at the verification boundary. One database transaction stores the delivery identity and durable outbox work, so a crash cannot strand a claimed event before it is queued.
const rawBody = await readRawBody(request)
verifyProviderSignature(rawBody, request.headers, WEBHOOK_SECRET)
const event = parseAllowedEvent(rawBody)
const receipt = await storeEventAndOutboxAtomically({
eventId: event.id,
payloadHash: sha256(rawBody),
event,
})
if (receipt.kind === 'duplicate') return providerAcknowledgement()
if (receipt.kind === 'conflict') {
await quarantineConflictingDelivery(receipt)
return providerConflictResponse()
}
await wakeOutboxDispatcherBestEffort()
return providerAcknowledgement()Fixture boundary: This pseudocode requires one atomic event-and-outbox transaction. A separate dispatcher leases and retries pending outbox work. Acknowledgement and conflict responses must follow the current provider contract; there is no universal 204 or 409 rule. The future webhook examples owner will provide runnable storage and worker code.
Make the choice in six accountable decisions
This is a review sequence, not a claim that every integration can be built in six steps. Each decision produces an artifact that a developer, operator, and product owner can inspect before credentials or customer data are involved.
- 01
Name the trigger and the owner of time
Write the event or question in one sentence. “When the customer opens the order page, show current status” is caller-initiated. “When the provider confirms payment, continue fulfillment” is provider-initiated.
Ready when: The team can identify which system knows that the exchange should start and whether a human is waiting for the answer.
- 02
Declare the source of truth
Choose the authoritative record for each state. Decide whether a webhook payload is the truth, a point-in-time snapshot, or only a signal to retrieve the latest object through an API.
Ready when: A delayed or out-of-order callback cannot move the business record backward or overwrite a newer authoritative version.
- 03
Define identity before retry behavior
For API mutations, define an operation key and request fingerprint. For callbacks, prefer the provider event or delivery ID. State how concurrent first delivery, exact duplicate, changed-content duplicate, expiry, and replay respond.
Ready when: The same intent or event can arrive twice without creating a second charge, message, booking, access grant, or record transition.
- 04
Draw the failure boundary
Separate network acceptance, durable business state, queued work, provider side effects, and user-visible completion. Name which state can be retried and how partial success is reconciled.
Ready when: A timeout or worker crash produces an inspectable pending or failed state instead of a false success screen or an unknown outcome.
- 05
Build the minimum security contract
Keep provider credentials server-side and scoped. For webhooks, preserve the exact bytes required by the provider and authenticate each delivery before parsing or acting. Apply business authorization after transport authentication.
Ready when: An invalid signature, a provider-defined stale signed attempt, revoked credential, wrong tenant, disallowed event, and oversized body all fail without blocking a legitimate authenticated redelivery.
- 06
Add reconciliation and an operator view
Store provider request or event identifiers, bounded status history, attempts, next retry, last error code, and a reconciliation cursor. Provide a reviewed replay or repair action instead of database edits.
Ready when: An operator can explain the current state, find a missing exchange, retry safely, and prove whether the downstream effect completed.
Test the exchange, the retry, and the repair path
A successful first request proves almost nothing about production behavior. Exercise invalid input, credentials, duplicate delivery, ambiguous timeout, order changes, and the exact published environment before real side effects are enabled.
| Model | Scenario | Expected evidence |
|---|---|---|
| API | Authorized current-state read | One bounded request returns the expected object ID, state, version, and provider request identifier. |
| API | Invalid input, revoked credential, rate limit, and timeout | Each response maps to a distinct internal state. Retry-After is honored when supplied, and an ambiguous mutation is reconciled before repetition. |
| Webhook | Valid signed event | Authentication precedes parsing, one durable claim is created, acknowledgement is bounded, and one worker applies the effect. |
| Webhook | Wrong signature with malformed JSON | The delivery is rejected at the authentication boundary without parsing, logging the raw body, or creating a business record. |
| Webhook | Exact duplicate and changed-content reuse of one event ID | A completed exact duplicate receives the documented acknowledgement without a second effect; changed content under the same identity is quarantined as a conflict. |
| Webhook | Legitimate provider redelivery after the first attempt | The current delivery signature is verified under the provider contract, then the provider event or delivery identity deduplicates the business effect. A redelivery is not rejected merely because the original event is old. |
| Both | Delayed or out-of-order callback | Version rules prevent regression, and an API reconciliation read restores current authoritative state. |
| Both | Published environment smoke | The API client and public HTTPS callback use environment-specific credentials, expose no secret, produce correlated records, and recover after one controlled retry. |
Security starts before the payload is trusted
Transport authentication and business authorization solve different problems. Verify who sent the request or callback, then decide what that identity may do to your own records.
- Keep API keys, OAuth tokens, webhook secrets, and signing keys in server-side configuration. Never put them in callback URLs, browser bundles, screenshots, analytics, source, or routine logs.
- Use least-privilege credentials and separate development from production. Record an owner and tested revoke or rotation path for every credential.
- For callbacks, cap request size, preserve the provider-required raw bytes, authenticate before parsing, and apply the provider’s current timestamp rule to each signed delivery. GitHub redelivery can preserve a delivery ID, while Stripe retries sign the new attempt; durable delivery or event identity prevents a repeated business effect.
- Treat provider authentication and internal authorization as different checks. A valid signature does not grant access to any customer, order, file, or tenant named by the payload.
- Redact routine telemetry. Prefer event ID, event type, bounded status, attempt, latency, and error code over raw payloads or personal data.
Six failure modes that reveal a weak boundary
An API mutation times out, but retrying might repeat the action.
- Likely cause
- The client lost the response after the provider may have committed the request, and no stable operation identity was defined.
- Check
- Search by the client operation key, provider request ID, or resulting business identity before sending the mutation again.
- Fix
- Add an application-defined idempotency contract and a status or reconciliation lookup. Do not assume POST is safe to repeat because the first response was missing.
The webhook endpoint times out during otherwise valid deliveries.
- Likely cause
- The handler performs database joins, external calls, email, or other slow side effects before it acknowledges the delivery.
- Check
- Compare acknowledgement latency with provider delivery logs and identify work performed before the durable event claim.
- Fix
- Authenticate, validate identity, durably claim or record the event, queue the slow work, and return the provider-documented success response.
A provider retry creates a duplicate side effect.
- Likely cause
- Deduplication exists only in process memory, or the event was marked complete before the effect and its reconciliation record committed.
- Check
- Restart the receiver between two identical deliveries and inspect the durable unique event identity and effect record.
- Fix
- Use a durable unique claim, explicit pending and complete states, and an outbox or equivalent boundary for downstream effects.
A valid webhook changes another customer’s record.
- Likely cause
- Provider authentication was mistaken for business authorization, and a payload tenant or object ID was trusted directly.
- Check
- Replay a valid signed fixture for the wrong tenant, account, installation, role, or revoked relationship.
- Fix
- Resolve provider identity to an internal account on the server, then authorize the target record separately before applying the event.
The local record is stale even though most callbacks succeeded.
- Likely cause
- The design assumes complete ordered delivery and has no cursor, version rule, changed-since query, or reconciliation job.
- Check
- Deliver fixtures out of order, omit one event, and compare the local version with an authoritative provider API read.
- Fix
- Make event application version-aware and run bounded API reconciliation on a schedule and after detected gaps.
Every callback signature fails after a framework change.
- Likely cause
- Middleware parsed, normalized, or re-encoded the request before provider-defined verification used the original bytes.
- Check
- Capture a controlled fixture at the network boundary and compare the verified byte sequence with the bytes documented by the provider.
- Fix
- Preserve exact raw bytes for the callback route, use the provider library when available, and re-run valid, mutated, stale, and rotation fixtures.
Webhook and API questions
Is a webhook an API?
A webhook is usually a callback-style API delivered over HTTP: one system calls an endpoint in another system after an event. “API” is the broader interface contract; “webhook” describes an event-delivery pattern. A webhook still needs a documented endpoint, message format, authentication, response, retry, and versioning policy.
Are webhooks faster than API polling?
A webhook can reduce the delay and wasted requests of periodic polling because the provider sends a callback after an event. It is not automatically real time or faster in every case. Provider queues, network delay, retries, receiver load, and background processing all affect when the business effect completes.
Do webhooks replace API calls?
Usually not. Webhooks are strong for timely signals. API calls remain useful for commands, current-state reads, pagination, setup, backfills, and reconciliation after missing or out-of-order events. A common design is webhook notification plus an API read for authoritative current state.
Should a webhook return 2xx before processing the event?
Follow the provider contract. A safe general boundary is to authenticate the exact delivery, validate its identity, durably claim or record it, enqueue slow work, and then acknowledge within the documented deadline. Returning 2xx before any durable claim can lose the event; completing every side effect before acknowledgement can trigger timeouts and duplicates.
How should duplicate webhook events be handled?
Store a stable provider event or delivery ID under a durable unique constraint, together with a payload fingerprint and pending or complete state. Verify the signature on the current delivery first. GitHub redelivery can preserve its delivery ID; Stripe retries use a new signature and timestamp while the event ID remains useful for deduplication. A completed exact duplicate receives the provider-documented acknowledgement without repeating the effect. Reuse of the same identity with changed content is quarantined and answered according to the provider contract.
Which is more secure, an API or a webhook?
Neither is inherently more secure. API clients must protect scoped credentials, validate responses, and control retries. Webhook receivers add an inbound attack surface and must verify the current delivery with the provider-defined signature or secret, apply the provider timestamp policy, deduplicate legitimate redelivery by durable identity, cap payloads, and authorize business records separately. Both need HTTPS, secret rotation, least privilege, bounded logs, and incident ownership.
When should I use both webhooks and API calls?
Use both when you need prompt notification and repairable state. Let the webhook signal that something changed, then use the API for a command, a current-state read, or reconciliation. Define whether the event payload is authoritative or only a hint, and prevent an older callback from overwriting a newer API version.
Can Playcode build API and webhook integrations?
Playcode can build API, webhook, token, or similar integration logic when the target service exposes a supported path and you provide the required credentials and requirements. Provider setup, permissions, policies, costs, signatures, rate limits, and live delivery still need provider-specific implementation and verification. This page does not claim a native or one-click connector.
Technical sources and verification date
IETF specifications establish HTTP and HMAC semantics. GitHub and Stripe documentation show how two real providers define webhook operations. Provider facts are examples of specific contracts, not evidence of one universal webhook protocol.
- IETF RFC 9110: HTTP Semantics · checked 2026-07-19HTTP request and response semantics, methods, status codes, idempotent methods, Retry-After, and message interpretation.
- IETF RFC 2104: HMAC · checked 2026-07-19The keyed-hash message authentication construction referenced as a general integrity primitive, not a provider-specific webhook format.
- GitHub Docs: Best practices for using webhooks · checked 2026-07-19Provider-specific guidance for secrets, HTTPS, timely acknowledgement, event typing, asynchronous work, and stable delivery identity on redelivery.
- Stripe Docs: Receive events at your webhook endpoint · checked 2026-07-19Provider-specific guidance for raw-body signature verification, asynchronous processing, retries, duplicate events, event ordering, and reconciliation through API reads.
- Playcode: AI App Builder · checked 2026-07-19Playcode positioning for building custom web applications with guided AI, subject to the provider and credential boundaries stated in this article.
- Playcode: Cloud · checked 2026-07-19Playcode runtime capabilities used by the CTA: backend, database, HTTPS, jobs, and recovery under current plan limits.
From boundary to running app
Build the integration around the failure path
Describe the provider, the request or event, the source of truth, credentials, retries, and recovery. Playcode can build the application and run its backend when the provider exposes a supported integration path.
You provide provider accounts, credentials, permissions, policies, and the final live-delivery smoke. No native or one-click connector is implied.