How to Test Third-Party API Integrations Before Production

What Should You Test Before Going Live?

A practical pre-production integration testing checklist covers both the outbound requests your application makes and the incoming webhooks your endpoints receive.

For a more comprehensive frontend-focused version of this checklist, see the complete API testing checklist for frontend teams.

Test Successful API Responses

Success responses look simple but require careful testing. Each 2xx status code has different semantics that affect how your application should behave.

• 200 OK — The request succeeded and the response body contains the result. Verify the payload structure matches your schema and the UI reflects the correct state.
• 201 Created — A new resource was created. Verify your application redirects to the new resource, updates a list, or shows a confirmation—not just ignores the response.
• 202 Accepted — The request was received but processing is asynchronous. Verify your application shows a pending state, polls for completion, or handles the webhook callback when processing finishes.
• 204 No Content — The action succeeded but there is no response body. Verify your parser does not throw when the body is empty, and the UI confirms success without trying to display response data.

Treating all 2xx responses identically is a common mistake. A 202 from a payment provider means the charge is pending—displaying it as confirmed is incorrect.

Test Authentication and Permission Failures

Authentication and authorization errors are among the most common integration failures in production. Teams often test that authenticated requests work but skip testing what happens when they do not.

The distinction between 401 and 403 matters:

• 401 Unauthorized means authentication is missing or invalid. The token is expired, the API key is wrong, or the signature does not match. Your application should prompt re-authentication or attempt a token refresh.
• 403 Forbidden means authentication exists but permission is denied. The credentials are valid but this account, plan, or user does not have access. Your application should show a clear permission error—not a generic failure.

Additional scenarios to test:

• Expired OAuth tokens — does the refresh flow work automatically?
• Missing API keys — is the error message clear enough to debug?
• Invalid HMAC signatures on webhooks — does your endpoint reject them correctly?
• Restricted accounts — does a downgraded plan break specific API calls?

For a broader overview of which status codes deserve dedicated test coverage, see HTTP status codes every frontend developer should test.

Test Rate Limits and Retry Behavior

Rate limit failures are invisible during development and catastrophic in production. Most third-party APIs enforce rate limits per API key, per user, or per account—and sandbox environments often have higher limits than production, making problems impossible to catch until real traffic hits.

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 30
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1717600000

{
  "error": "rate_limit_exceeded",
  "message": "Too many requests. Retry after 30 seconds."
}

Simulate this response and verify:

• Your application reads the Retry-After header and waits the correct interval before retrying.
• Exponential backoff is implemented—not immediate repeated retries that make the rate limit worse.
• Actions are disabled or queued during the rate limit window, preventing duplicate submissions.
• The user sees appropriate feedback instead of a silent failure or a raw API error.

Test Slow Responses and Timeouts

External APIs have bad days. A normally fast endpoint can take 5–10 seconds under load. Without explicit timeout handling, those slow requests degrade every user experience they touch.

Test by simulating a delayed response and verifying:

• Loading states appear immediately and remain visible during the delay. Users should never see a frozen UI.
• A timeout threshold is set. Requests that take longer than the threshold are cancelled rather than waiting indefinitely.
• Retry UI is shown when a request times out—not just a generic error.
• Long-running operations are processed as background jobs, not inline requests that block page rendering.
• Mobile users on slower connections hit the same loading and timeout states. Test at 1–3 second delays, not just 200ms.

Simulating slow responses during development is one of the most effective ways to catch missing loading states before users find them. See how to simulate API responses for frontend development for a deeper look at this workflow.

Test Webhooks and Incoming Requests

Outbound API calls are only half of most integrations. Webhooks—events pushed from a third-party service to your endpoint—require a different testing approach because you do not initiate them.

For each webhook integration, test:

• Incoming payloads. Inspect the full request body and confirm your handler parses the event type, ID, and data fields correctly.
• Headers. Verify authentication headers like Stripe-Signature, X-Hub-Signature-256, or custom tokens are present and your validation logic rejects invalid ones.
• Signature validation. Cryptographic signatures prove the payload came from the provider. Confirm your validation logic rejects tampered payloads.
• Event types. Each event type may require different handler logic. Test each event type explicitly—not just the most common one.
• Duplicate webhook deliveries. Providers guarantee at-least-once delivery. Send the same event twice and confirm your handler is idempotent.
• Failed delivery behavior. What does the provider do when your endpoint returns a 500? Does it retry? For how long? Does it alert someone?

This is where request catcher workflows are especially useful. A request catcher gives you a live public URL that captures exactly what the provider sends, with full header and payload inspection. See how to debug webhooks and inspect incoming requests for the full workflow.

Test Custom Responses From Your Webhook Endpoint

Many integrations depend not just on what your endpoint receives but on what it returns. Webhook senders read your HTTP response and make decisions based on it—retry on 500, disable the integration on repeated 4xx, pause a workflow on timeout.

MockFlow's Request Catcher lets developers inspect incoming requests and configure the response returned to the caller. Response controls include:

• HTTP status code — return 200, 202, 400, 401, 404, 500, or any other code.
• Response body — return JSON, plain text, or an empty body to test how the provider parses your response.
• Response headers — add custom headers like Retry-After, X-Request-ID, or Content-Type.
• Response delay — introduce latency to simulate slow processing, trigger timeout behavior, and test retry schedules.

This allows teams to test both sides of an integration simultaneously—what was received in the payload and what gets returned to the provider—without writing any backend code. For more detail on this workflow, see how to test webhooks by returning custom responses.

Example: Testing a Payment Provider Integration

A payment provider like Stripe sends a webhook event when a payment succeeds. Your endpoint receives something like:

POST /webhooks/payments
Content-Type: application/json
Stripe-Signature: t=1717600000,v1=abc123...

{
  "type": "payment_intent.succeeded",
  "data": {
    "id": "pi_123456",
    "amount": 4900,
    "currency": "usd"
  }
}

Test the following scenarios against this incoming event:

• Return 200 OK. Stripe marks delivery as successful. Verify your handler processes the payment, updates the order status, and does not process it again on a second identical delivery.
• Return 500 Internal Server Error. Stripe schedules a retry. Inspect the retried requests—is the payload identical? Does your system handle duplicate processing? What happens after the retry window closes?
• Return a delayed response.Set a delay above Stripe's timeout threshold. Verify that Stripe retries, that your system handles the eventual retry, and that loading states or queued jobs behave correctly.
• Return a custom header. Verify that Stripe ignores unexpected response headers and that your logging captures the outgoing headers for auditability.

Example: Testing a CRM Integration

CRM integrations push and pull contact and deal data in real time. A few scenarios that are easy to miss during development:

• New lead created successfully. Verify the record is created with all required fields, the response contains the new resource ID, and your application stores it for future updates.
• Duplicate lead. The CRM returns a 409 Conflict or a 200 with a reference to the existing record. Verify your system detects the duplicate and does not create a second record.
• Invalid email address. The CRM returns a 422 Unprocessable Entity with field-level validation errors. Verify those errors are surfaced to the user clearly, not swallowed silently.
• Permission failure. The API key does not have write access to the CRM. A 403 is returned. Verify your error handling logs the failure and shows a meaningful message to the operator.
• Rate limit response. The CRM returns 429 with a backoff window. Verify the retry queue processes the lead after the backoff period instead of dropping it.

Using Mock APIs for Outbound Integration Testing

When your application makes outbound calls to a third-party service, mock APIs let you simulate exactly what that service would return—without hitting the real service, consuming rate limit quota, or depending on sandbox availability.

A mock API configured to simulate a third-party service can return:

• Fake success responses — realistic JSON payloads for 200 and 201 responses, matching the schema of the real service.
• Validation errors — 400 and 422 responses with field-level error messages to verify form and request validation logic.
• Rate limit responses — 429 with a Retry-After header to test exponential backoff.
• Server errors — 500 and 503 responses to test circuit breakers, fallback logic, and retry handling.
• Slow responses — delayed responses to test loading states, timeout thresholds, and background job behavior.

Mock APIs give development and QA teams control over the third-party service's behavior, making it possible to test edge cases that are impossible to trigger reliably in a live sandbox. See how to simulate API responses for a practical walkthrough.

Using MockFlow for Integration Testing

MockFlow provides two tools that cover both sides of third-party integration testing: a mock API builder for outbound calls and a Request Catcher for incoming webhook testing.

Mock API for Outbound Calls

• Create mock API endpoints that simulate any third-party service response.
• Configure status codes, response bodies, headers, and response delays.
• Test success paths, error paths, rate limits, and slow responses without hitting real APIs.

Request Catcher for Incoming Webhooks

• Create a request catcher URL and point any webhook provider at it.
• Inspect incoming request payloads, headers, and event types in real time.
• Configure the response your endpoint returns—status code, body, headers, and delay.
• Test retry behavior by returning 500 and observing subsequent delivery attempts.
• Test timeout behavior by setting a response delay above the provider's threshold.

Both tools work entirely in the browser with no setup required.

Best Practices for Third-Party API Integration Testing

• Test both happy path and failure path. Most production incidents come from untested failure scenarios, not untested success flows.
• Inspect headers on every request. Authentication tokens, idempotency keys, correlation IDs, and rate limit counters are all in headers— verify they are present and correct.
• Validate payload structure explicitly. Do not assume the schema matches documentation. Capture a real request and test against the actual fields.
• Test retries deliberately. Return a 500 and verify your system handles the retry correctly without processing the event twice.
• Test duplicate events. Webhook providers send the same event multiple times. Confirm your handlers are idempotent before going live.
• Test rate limits explicitly. Simulate 429 responses and verify your retry logic respects Retry-After headers.
• Simulate delays at realistic thresholds. Test at 1s, 3s, and 10s delays to catch missing loading states and tight timeout configurations.
• Avoid relying only on sandbox environments. Sandbox APIs often have different behavior, higher limits, and simplified responses compared to production.
• Log integration failures. Structured logs of failed requests, status codes, and payload snippets make production debugging significantly faster.
• Document expected responses. For each integration, document which status codes trigger which application behavior. Include this in runbooks so on-call engineers know what to expect.

Common Mistakes Teams Make

• Only testing successful responses. The happy path passes, the integration ships, and the first 401 in production causes a silent failure that nobody notices for days.
• Ignoring rate limits. Sandbox environments rarely enforce the same limits as production. Real traffic triggers 429 errors that no one has ever handled.
• Not testing webhook retries. The provider retries on 500. Your system processes the same payment twice. The user is charged twice. This is completely preventable.
• Not validating signatures. Skipping HMAC signature validation means any caller can send fake webhook events to your endpoint.
• Assuming response format never changes. Third-party APIs evolve. A new field added to the response body can break a strict parser that did not expect it.
• Not handling duplicate events. Assuming at-most-once delivery when the provider guarantees at-least-once leads to data integrity issues under real load.
• Exposing raw errors to users. Returning the raw third-party error message to end users leaks internal API details and creates a poor experience. Map external errors to user-friendly messages.