API and webhook testing

What API and webhook testing covers

A defect in a platform API repeats in every integrator's money flow. A retried payout that the API does not deduplicate pays twice, and a webhook that never arrives leaves an invoice open or a card unfrozen at every client that relies on the event. We test the public and partner APIs of platforms that other fintechs build on, such as banking-as-a-service platforms, acquirers, open banking providers, KYC services, billing, chargeback, and payroll platforms.

Contract tests from the specification

The suite is generated from your OpenAPI document and runs every documented operation. Since OpenAPI 3.1.0 (15 February 2021), a top-level webhooks field describes incoming webhooks that the API consumer may choose to implement, so event payloads get the same schema checks as responses. The current version is OpenAPI 3.2.1, published 10 September 2026.

Checks per operation:

• every documented status code is reachable, and no undocumented status code or field appears;
• required fields, types, formats, and enum values match, including amounts as integer minor units or decimal strings as documented;
• invalid requests return the documented 4xx error body, not a 500;
• pagination, filtering, and tenant scoping return only the caller's records.

A response that drifts from the schema breaks client SDKs generated from that schema. The contract versus end-to-end comparison shows where each test type catches it.

Idempotency keys and retries

RFC 9110 section 9.2.2 does not list POST as idempotent, so a payment or transfer POST needs an application-level key. The IETF Idempotency-Key header draft 07 of 15 October 2025 expired on 18 April 2026 and is not an RFC (checked 2026-09-16). We test against your documented rule and use the draft as the reference where your rule follows it. Test cases:

• Retry after completion. The same key and body return the stored result, success or error, with one side effect (section 2.6).
• Key reused with another body. Section 2.2 says the key MUST NOT be reused with a different payload; section 2.7 says the resource SHOULD reply 422.
• Concurrent retry. A retry sent while the original is still processing SHOULD receive 409 (section 2.7). We send parallel requests to find races that create two records.
• Missing key. An operation documented as requiring the key SHOULD return 400 with a link to documentation (section 2.7).
• Expiry and scope. Section 2.5.2 says resources MUST publish an idempotency specification that includes expiration policy if applicable. We measure the real expiry window and confirm that one tenant's key never returns another tenant's response.

Retries also cover timeouts where the server commits after the client disconnects, and 429 or 503 responses with Retry-After. The payment idempotency testing guide shows the request sequences.

Webhook signatures, ordering, and replay

We test your documented scheme. For platforms that adopt the Standard Webhooks specification (checked 2026-09-16), the checks follow it:

• webhook-id, webhook-timestamp, and webhook-signature headers on every event;
• a signature over msg_id.timestamp.payload with v1 HMAC-SHA256 or v1a Ed25519, computed on the raw body;
• two space-delimited signatures during secret rotation, with both verifying;
• a redelivery that keeps the same webhook-id, which the specification recommends consumers use as an idempotency key;
• any non-2xx response, including 3xx, counts as a failure to retry, and after 410 Gone the sender should disable the endpoint.

Ordering tests deliver a refund event before its capture event, and a stale status after a newer one. Each event must carry enough data, such as a resource version or timestamp, for a consumer to discard the stale one. The webhook reliability guide covers receiver-side tests.

Versioning and backward compatibility

The released and candidate specifications are compared operation by operation. Breaking changes include a removed field, a new required request field, a narrowed enum, a changed type, and a changed default. A new enum value in a response is flagged against your version policy, because strict clients reject unknown values. Recorded requests from each supported SDK version replay against the candidate build. Deprecated operations are checked for the Deprecation header of RFC 9745 and the Sunset header of RFC 8594; RFC 9745 section 4 says the Sunset timestamp MUST NOT be earlier than the Deprecation timestamp.