Third-party API integration sequence
Request, webhook callback, retry, and fallback handling.
Integrating a third-party service — a payment processor, shipping carrier, analytics platform — sounds simple until the network hiccups. This template shows the full lifecycle: your app sends a request, the external service returns a 202 Accepted with a job ID, and later calls your webhook to report the result. When the webhook fails (network timeout, your server down), it retries with backoff. When retries exhaust, your app falls back to polling the external API directly.
The distinction between the happy path (webhook succeeds immediately) and the retry-then-fallback path is where most integration bugs hide. This diagram makes both visible, so your team knows which code to test and what happens when a webhook stalls.
When to use this template
- Designing a new integration — agree with your team on the happy path (async request → webhook callback) and the fallback (polling) before writing code, so error paths are consistent and testable.
- Debugging stuck integrations — if webhooks are not arriving, the diagram helps you reason through: is the external service actually calling your webhook, or did your retry queue get stuck?
- On-call runbooks — when a third-party integration silently fails, this diagram is the diagnostic checklist: are webhooks being received? Are signature validations passing? Is the fallback polling kicking in?
How to adapt it
Customize the participants and messages to your specific integration:
- Replace ExtAPI with the real service name (Stripe, Shippo, Twilio) and adjust the callback format to match its actual webhook payload.
- Add queue deduplification (skip retries if you already processed this job_id) to prevent duplicate side effects.
- Extend the fallback to show alerting: if polling finds a stale job, send an alert so on-call knows the webhook path is broken.
Visual edits regenerate the sequence syntax, so you can sketch callback paths and error handlers without learning sequence diagram notation.
Mermaid code
Copy it anywhere Mermaid is supported — GitHub, Notion, or your docs.
sequenceDiagram
participant App
participant ExtAPI as External API
participant Queue
participant Webhook as Webhook Handler
participant Fallback
App->>ExtAPI: POST /request (async job)
ExtAPI-->>App: 202 Accepted + job_id
App->>Queue: Enqueue callback listener
ExtAPI->>Webhook: POST /webhook (job complete)
Webhook->>Webhook: Validate signature
alt Webhook succeeds
Webhook->>App: Mark job complete
else Webhook fails or timeout
Webhook->>Queue: Re-queue with backoff
Queue->>Webhook: Retry (up to 3x)
alt Retry succeeds
Webhook->>App: Mark job complete
else All retries fail
Webhook->>Fallback: Fallback handler
Fallback->>ExtAPI: Poll status
ExtAPI-->>Fallback: Job status
Fallback->>App: Finalize with polled result
end
end
Frequently asked questions
- Why do third-party APIs use webhooks instead of returning the result immediately?
- Most integrations (payment processors, shipping carriers, mapping services) are asynchronous: the request kicks off a job server-side that takes seconds to minutes. A webhook callback notifies your app when the job finishes, avoiding your app from polling. If the webhook fails, you have a fallback: poll the API yourself or retry.
- What is webhook signature validation and why does the diagram show it?
- External services sign their webhook requests with an HMAC so your app can verify the message came from the real service, not an attacker. Validating the signature is the first step after receiving the webhook. If validation fails, reject the request immediately rather than processing spoofed data.
- Why does the diagram show a queue and retry backoff?
- Network calls fail unpredictably — timeouts, temporary 5xx errors, rate limits. A queue with exponential backoff (wait 1s, then 2s, then 4s) gives transient errors time to recover without hammering the external service. Most webhooks retry 3–5 times before giving up.
- When should I use polling instead of webhooks?
- Use polling when the external API does not support webhooks, or when you need real-time visibility into job progress. Polling scales poorly (you call the API every 5–10 seconds for minutes), so it's a fallback. This diagram shows the hybrid: webhooks for efficiency, polling when webhooks exhaust retries.