Secure Payment Webhooks for Paid APIs

Secure payment webhooks are the bridge between a paid API call and the seller systems that need to react after payment. An AI agent may call an endpoint, receive an `HTTP 402 Payment Required` response, pay in USDC on Base through an x402-style flow, and retry with proof. The live path verifies the payment and serves the protected result. After that, webhook events can notify internal tools, update dashboards, prepare settlement records, and feed reconciliation workflows.

That makes webhooks powerful, but also easy to misuse. A webhook is an inbound request from outside the seller's application boundary. If it can change payment status, trigger fulfillment, release settlement, or mark records as exported, it needs a verification model. Otherwise a seller may end up trusting a JSON payload because it looks plausible.

Apiosk is built around the operating layer for agent payments: get paid by AI, accept crypto in through x402-style payment flows, support euros-out workflows, keep seller controls non-custodial where relevant, bundle micropayments, and preserve records for settlement and reconciliation. Secure webhooks help those records reach the seller's own systems without turning every event into a trust problem.

Keep webhook trust separate from payment verification

The first design rule is separation. Payment verification belongs in the live payment flow. Webhook verification belongs at the event delivery boundary.

In a paid API flow, the protected endpoint should not run because a webhook arrived. It should run because the request presented valid payment proof under the current payment requirement. The webhook can then report what happened: payment required, payment verified, execution completed, execution failed, bundle assigned, settlement updated, or export created.

This separation prevents fragile dependencies. If a seller's webhook receiver is temporarily down, a valid paid API call should not automatically fail unless the seller has configured a review hold. If a webhook is delayed, the payment record should still exist. If a webhook is duplicated, the seller should process it idempotently instead of creating duplicate revenue or support records.

The webhook receiver is therefore a consumer of payment events, not the authority that decides whether the agent paid.

Verify signatures before parsing business meaning

Signature verification should happen before the receiver trusts the event. The exact implementation depends on the platform, but the pattern is consistent: the sender signs the raw payload and timestamp with a shared secret or signing key, and the receiver recomputes the signature before accepting the event.

For payment webhooks, validate:

• The signature matches the raw request body.
• The timestamp is within an accepted tolerance.
• The event id has not already been processed.
• The signing secret belongs to the expected seller account or environment.
• The event type is allowed for that webhook destination.

Raw body handling matters. If middleware parses and reserializes JSON before verification, formatting or encoding changes can break signature checks. Keep access to the original bytes until the signature is verified.

When verification fails, reject the request with a clear non-success response and do not apply business updates. Do not silently accept unsigned events into a review queue that later becomes indistinguishable from trusted payment activity.

Protect against replayed events

A signed payload can still be dangerous if it can be replayed indefinitely. Replay protection makes an old valid event unusable as a new instruction.

Use two controls together. First, require a signed timestamp and reject events outside a short tolerance window. Second, store processed event ids and make event handling idempotent. If the same event arrives again, the receiver can return success without repeating side effects.

Idempotency is especially important for paid agent APIs because retries are normal. Delivery systems retry webhooks after timeouts. Agents retry API calls after ambiguous responses. Payment gateways may emit later lifecycle events for the same request. The seller should distinguish a duplicate delivery from a new payment event.

A useful event record can include:

• `event_id`
• `event_type`
• `created_at`
• `payment_requirement_id`
• `request_id`
• `payment_reference`
• `verification_status`
• `execution_status`
• `settlement_status`
• `processed_at`

That record lets the seller answer whether the webhook was accepted, ignored as a duplicate, rejected, or parked for review.

Use event types that match the payment lifecycle

Webhook security is easier when event types are precise. A vague event such as `payment_updated` forces receivers to infer too much. A better model maps lifecycle events to operational decisions.

For paid API traffic, useful event types may include:

• `payment_requirement.created`
• `payment_proof.verified`
• `payment_proof.rejected`
• `api_execution.completed`
• `api_execution.failed_after_payment`
• `settlement_bundle.assigned`
• `settlement_bundle.ready`
• `reconciliation_export.created`

The seller does not need every destination to receive every event. Analytics might need paid execution summaries. Finance may need bundle and export events. Support may need request, proof, and execution status. Event selection is part of seller control.

This matters for non-custodial operations too. Sellers should control which wallets, assets, networks, endpoints, and webhook destinations are active. A webhook should reflect those controls, not bypass them.

Preserve the identifiers finance will need later

Secure delivery is only half the job. The webhook payload also needs the identifiers that make paid agent traffic explainable.

An agent-paid API call is more than a transfer. The seller needs to know what was bought, which price was shown, which payment proof was verified, whether the API delivered the result, and how the payment will appear in settlement. If the webhook only says "USDC received," downstream systems still have to guess.

For Apiosk-style operations, webhook payloads should preserve endpoint id, paid unit, request id, payment requirement id, amount, token, network, payment reference, verification status, execution status, idempotency key, buyer or agent reference where available, bundle id, settlement state, and reconciliation export reference when relevant.

European sellers often want business records in euros even when the agent paid in USDC. The webhook does not need to make accounting, tax, or legal decisions. It should preserve enough operational context that the seller's own finance process can connect crypto in to euros out.

Test failures before production traffic

Webhook tests should cover more than a successful event. Before relying on payment webhooks, test invalid signatures, stale timestamps, duplicate event ids, unsupported event types, wrong environment secrets, delayed delivery, receiver timeouts, and schema version changes.

Also test business edge cases. What happens if payment verifies but API execution fails? What if the agent retries with the same idempotency key? What if a valid payment is held from settlement because the amount does not match the active policy? What if an export event arrives before a downstream finance system is available?

These tests make the receiver boring in production. Normal events update records. Duplicate events do not repeat side effects. Invalid events fail closed. Delayed events remain traceable. Exceptions move into review with a reason.

A practical receiver flow

A secure webhook receiver for paid APIs can follow a simple sequence:

1. Capture the raw request body and signature headers. 2. Verify signature, timestamp, seller account, and environment. 3. Check whether `event_id` was already processed. 4. Validate the event schema and allowed event type. 5. Apply the smallest necessary state change. 6. Store the event, processing result, and related identifiers. 7. Return a success response only after the event is safely recorded.

The state change should be narrow. A `payment_proof.verified` event can update payment status. It should not automatically mark settlement as complete. A `settlement_bundle.ready` event can update the bundle record. It should not rewrite the original payment requirement. Keeping event effects narrow makes webhook processing easier to audit.

Where Apiosk fits

Apiosk helps sellers operate paid APIs for AI agents without forcing every buyer through a human checkout. The agent-facing side can use x402-style payment requirements, USDC on Base, and clear proof verification. The seller-facing side can use records, seller controls, bundled micropayments, euro settlement context, and reconciliation exports.

Secure payment webhooks connect that operating layer to the seller's own stack. They let internal systems react to paid API events while preserving trust boundaries: signed delivery, replay protection, idempotent processing, clear event types, and stable identifiers.

For a first implementation, start with one webhook destination and a small event set. Verify signatures against the raw payload. Store event ids. Treat duplicate delivery as normal. Keep payment verification in the live x402 path. Include the identifiers that connect request, proof, execution, bundle, and reconciliation. That is enough to make webhooks useful without letting them become a hidden source of payment truth.