Webhook Reliability Guide for digital advertising teams

Webhook reliability for advertising card operations

Advertising card operations produce fast-moving events: verification holds, threshold billing, reversals, refunds and decline notifications. A reliable webhook design helps the platform explain what happened without making support guess from screenshots or a single displayed balance.

Events that must be safe to replay

• Card load requested and card load posted.
• Merchant authorization created, updated or reversed.
• Settlement posted against a previous authorization.
• Refund received against a settled transaction.
• Card frozen, unfrozen, closed or restricted.
• Provider incident or delayed delivery notification.

Worked operating case

An agency runs a campaign with an expected spend of USD 80 per day and a platform billing threshold near USD 250. The card is loaded for a controlled operating window. The advertising platform first creates a small verification hold, then later posts a settlement. If the same settlement webhook is delivered twice, the second delivery should update delivery metadata only; it must not create a second debit.

Reliability controls

1. Verify signature, timestamp and key version before processing the body.
2. Store the provider event ID and business object ID before posting ledger changes.
3. Process events idempotently so repeated delivery cannot duplicate money movement.
4. Keep authorization, settlement, reversal and refund as linked but distinct lifecycle states.
5. Alert on old pending holds, unmatched settlements and negative available balances.

Failure boundaries

Pause automated processing when the signature is invalid, the event arrives for an unknown card, the settlement exceeds the related authorization without a documented rule, or the webhook would create a duplicate ledger entry. A card platform should prefer a reviewed exception queue over silent balance edits.

Additional FAQ

Should webhooks be trusted without reconciliation?

No. Webhooks are delivery messages. They should be verified, stored and reconciled against card and wallet ledgers.

What should support see?

Support should see event ID, received time, processing result, related transaction ID and whether the event changed money, status or only delivery metadata.

Frequently asked questions

What should be checked before the first transaction?

Confirm the displayed fees, available balance, supported use case, card status and merchant requirements. Start with a controlled amount and retain the resulting ledger entry.

Does a virtual card guarantee merchant acceptance?

No. Acceptance depends on the issuer program, merchant rules, geography, verification requirements and current risk controls.

How should teams evaluate operational quality?

Review fee disclosure, card controls, transaction detail, refund handling, support channels, API idempotency and incident procedures.