Receive payment events

Webhooks notify your server when a payment, refund, or HMS channel-confirmation result changes. Use them to update your business records and schedule fulfillment without depending on a customer keeping your app open.

1. Configure your receiver

Create an HTTPS endpoint on your backend and register it through the application's webhook settings in Console. Obtain the signing secret and key ID through the authorized setup flow. Store the key together with its endpoint, application, environment, and validity information.

Endpoint configuration, signing-key changes, and replay controls are Console workflows. A customer API key is not a webhook-management credential.

2. Complete endpoint verification

NextAppMarket sends a signed endpoint.verification event with an expiring challenge. Verify the signature and endpoint binding, check the expiry, and echo the challenge as JSON:

{"challenge": "THE_RECEIVED_CHALLENGE"}

Return HTTP 200 with Content-Type: application/json. Echo only the challenge you received from a valid, unexpired request for the configured endpoint. This exchange proves receiver control; it does not indicate a payment.

3. Subscribe your processing logic to events

Event type	Meaning
payment.succeeded	The order is paid.
payment.failed	The order has a confirmed failed result.
payment.closed	The order is closed.
refund.succeeded	The refund's execution status is succeeded.
refund.failed	The refund's execution status is failed.
hms.confirmation.required	Channel confirmation is awaiting your fulfillment attestation.
hms.confirmation.completed	Required channel confirmation is confirmed.

The envelope contains event_id, schema_version, type, app_id, environment, occurred_at, resource_version, and data. Endpoint-verification events have their own challenge schema.

See the complete payment-success example. Customer notifications omit external_order_id, client_user_id, and raw purchase evidence. Resolve the event through your stored platform order ID.

4. Persist before acknowledging

Process delivery in this order:

1. Preserve the exact raw request body.
2. Verify the signature and signed content.
3. Validate the event schema and its application/environment binding.
4. Insert the event into a durable inbox and enqueue the business work in the same transaction.
5. Return 2xx after that transaction commits.
6. Let a worker perform the idempotent business update and mark the inbox item processed.

Use a unique inbox key that includes the trusted application/endpoint context and event_id. If multiple receivers process the same application's facts, share a business deduplication key across them. A repeated event with the same bytes can be acknowledged after confirming its original durable record.

For external fulfillment, such as calling another service, persist an idempotent delivery command that can resume after a crash. Returning 2xx must not make unfinished work disappear.

Handle retries and ordering

Retries and manual replays retain the original event_id and body bytes but receive a new timestamp and signature. Deduplicate by event identity, not signature. Compare resource_version within the same resource so an older event cannot replace newer state.

Do not rely on a particular delivery order. An event updates a resource; it is not a guarantee that you have received every preceding event. Query the resource when you need to reconcile a gap.

Events are delivered by the US service after payment facts are synchronized. If delivery is delayed, the Payment API remains the recovery path for authoritative payment queries. Use Console delivery records to investigate or request an explicit replay of retained events.

Change a signing key

Add the replacement key to your receiver before directing deliveries to use it. During an authorized overlap, accept each valid key only for its assigned endpoint and application. Remove the old key when its overlap ends; a revoked key must stop working immediately.