What is a payment webhook?

A payment webhook is an automated message that a payment provider sends to a merchant-controlled web address when a subscribed event occurs. It lets the merchant's server learn about events such as a completed payment, an unsuccessful attempt, or a later status change without depending on the customer's browser to report the result. The exact event names, message fields, delivery rules, and setup steps vary by provider.

The short answer

A webhook is a server-to-server notification. The merchant registers an HTTPS endpoint and chooses supported event types. When one of those events occurs, the provider sends an HTTP request, commonly a POST containing structured event data, to that endpoint. The receiving application verifies the message, records the event, acknowledges receipt, and then performs the appropriate business action.

Webhooks are useful because many payment outcomes happen outside the browser session. A customer may close a tab, lose connectivity, or use a payment method whose final state arrives later. A provider event can give the merchant's back-end system a separate signal to update an order, notify staff, or begin a reconciliation step. It should still be processed according to the provider's current documentation rather than treated as a universal format.

How a payment webhook works

The merchant creates an endpoint. A developer deploys a server route that can receive the provider's supported webhook requests over HTTPS.
The endpoint subscribes to events. The merchant selects only the event types the application needs and stores the endpoint configuration in the provider account.
The provider creates an event. A payment or account action produces an event under that provider's data model.
The provider sends a notification. The provider posts an event payload and authentication information to the registered endpoint.
The application verifies and acknowledges it. The endpoint checks the provider's documented signature or verification mechanism and returns the required successful HTTP response promptly.
Business processing continues safely. The application records the event, prevents duplicate work, and performs longer tasks through an appropriate processing workflow.

For context on the transaction itself, review how online credit card payments work. A webhook carries an event notice; it is not the complete payment flow.

Webhook, return page, and API request are different

Browser return page

A return page gives the customer a destination after checkout. It can display next steps, but the customer's browser may never reach it. A redirect alone should not be the sole operational signal for fulfillment.

Webhook notification

A provider sends an event directly to a registered server endpoint. This separates back-office handling from the customer's tab and supports events that occur after the checkout visit.

API status request

The merchant's application asks the provider for the current state of a payment or related object. This can supplement webhook handling when the application needs to confirm or reconcile a status.

A hosted payment page may use both a browser return route and a webhook. Merchants should document what each channel is allowed to do so that customer messaging and fulfillment do not become confused.

Operational safeguards to plan

Verify every notification

Use the selected provider's current signature-validation or message-verification procedure before trusting the payload. Verification secrets belong in protected server-side configuration, not browser code, URLs, analytics, tickets, or general forms.

Acknowledge before slow work

Official provider documentation commonly instructs endpoints to return a successful response promptly. Record enough information to continue safely, then move email, fulfillment, reporting, and other slower work outside the immediate request when the application architecture allows it.

Expect another delivery

Providers can retry notifications when delivery is not acknowledged. The handler should recognize an event it has already processed and avoid creating a second shipment, receipt, or order-state change from the same logical event.

Do not assume event order

Events may not arrive in the sequence the merchant expects. Use stable event and object identifiers, store processing history, and retrieve the current object state through the documented API when the workflow requires confirmation.

What merchants should define before launch

Event scope: List the specific events the business needs and the action allowed for each one. Avoid subscribing to unused events merely because they are available.
Source of truth: Decide which authenticated provider status permits fulfillment, cancellation, customer communication, or manual review.
Duplicate protection: Store provider event identifiers and make each business action safe to run no more than intended.
Failure monitoring: Alert an owner when verification fails, the endpoint returns errors, processing is delayed, or deliveries remain unresolved.
Test coverage: Exercise successful, unsuccessful, delayed, repeated, and out-of-order events in the provider's test environment before production.
Version ownership: Track the API or event version used by the endpoint and assign responsibility for provider notices and integration changes.
Reconciliation path: Give staff a documented way to compare orders, provider records, and stored events without exposing sensitive payment data.

The ecommerce and online payments FAQ hub connects webhook planning with checkout, gateways, hosted fields, and broader online payment operations.

Privacy and access boundaries

A webhook endpoint should receive only the events and fields required for its documented job. Limit access to configuration, logs, replay tools, and provider dashboards according to staff responsibilities. Keep secret API keys and webhook secrets out of source control and client-side code, and avoid logging full payloads unless the data has been reviewed and protected under the business's retention rules.

For troubleshooting, use safe references such as an internal order number, provider event identifier, timestamp, and non-sensitive status. Never ask a customer or employee to place full card numbers, security codes, passwords, bank credentials, complete account numbers, or secret API keys into a general inquiry. Merchants comparing form boundaries can also read what hosted payment fields are.

Questions merchants often ask

Does a webhook replace every API request?

No. A webhook announces an event, while an API request can retrieve a current record or perform an authorized action. Many integrations use both, with responsibilities defined for each channel.

Can a webhook arrive more than once?

It can. Provider retry behavior differs, so the receiving application should identify previously handled events and make business actions resistant to duplicate delivery.

Should the endpoint trust the JSON body?

Not by itself. The application should validate the message using the provider's documented verification method and preserve the original request format when that method requires it.

Who should own webhook monitoring?

Assign a named technical or operations owner who can review failures, reconcile affected orders, manage endpoint changes, and coordinate with the selected provider when documentation or delivery behavior changes.

Map the event workflow before implementation

Document the provider event, verification step, acknowledgment, stored identifiers, permitted business action, duplicate guard, failure alert, and reconciliation path. Then compare that design with the provider's current documentation and test representative event states end to end.

Discuss an ecommerce payment workflow

Do not include cardholder data, passwords, bank credentials, complete account numbers, webhook secrets, or API keys in a general inquiry.

To learn more about how TSYS can help improve the way your organization accepts payments, markets to new customers, or manages its HR responsibilities, get in touch by calling 585-981-8463 to get started.