Receive and verify Alipay (Antom / Alipay+) webhook notifications. Use when setting up Alipay webhook handlers, debugging RSA256 Signature header verification, or handling payment events like notifyPayment, notifyCapture, notifyRefund, notifyAuthorization, and notifyDispute.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
Receive and verify Alipay (Antom / Alipay+) webhook notifications. Use when setting up Alipay webhook handlers, debugging RSA256 Signature header verification, or handling payment events like notifyPayment, notifyCapture, notifyRefund, notifyAuthorization, and notifyDispute.
Alipay's global / cross-border products — Antom (Cashier Payment / AMS) and
Alipay+ — deliver asynchronous webhook notifications (notifyPayment,
notifyRefund, notifyCapture, notifyAuthorization, notifyDispute) signed
with an asymmetric RSA256 (SHA256withRSA) scheme carried in a Signature
header. This skill targets that header-based scheme.
Legacy note: The older Alipay openapi / MAPI integration
(openapi.alipay.com, global.alipay.com) is a different, unrelated
scheme — form-encoded params with sign + sign_type=RSA2, verified by
stripping sign/sign_type, sorting the remaining params A–Z, joining with
&, and replying with the plain text . If your integration posts
bodies with a field, you are on
that older vintage — this skill does cover it. Everything below is the
modern Antom/Alipay+ header RSA256 scheme.
success
application/x-www-form-urlencoded
sign
not
When to Use This Skill
How do I receive Alipay / Antom / Alipay+ webhooks?
How do I verify the Alipay Signature header (RSA256 / SHA256withRSA)?
How do I handle notifyPayment, notifyRefund, or notifyDispute events?
Why is my Alipay webhook signature verification failing (base64URL encoding)?
How do I sign the acknowledgement response Antom expects?
Verification (core)
Alipay/Antom signs each request with SHA256withRSA using its private key and
carries the result in a Signature header. You verify it with Antom's public
key (from the Dashboard). Three details trip people up:
The signed content is exactly two lines: <METHOD> <URI> then
<Client-Id>.<Request-Time>.<RawBody> joined by single periods.
The signature is base64URL encoded (URL-safe alphabet), and is often
additionally percent-encoded on the wire — URL-decode, then base64-decode.
Use the raw request body — never re-serialize parsed JSON first.
Signing the acknowledgement — unlike most providers, Antom expects the ack
itself to be signed with your private key over the same two-line content
(<METHOD> <URI>\n<Client-Id>.<Response-Time>.<ResponseBody>), returned in a
Signature header alongside Client-Id and Response-Time. See the examples.
If the ack is missing or non-200, Antom retries ~8 times over 24 hours
(0s, 2m, 10m, 10m, 1h, 2h, 6h, 15h). Make your handler idempotent.
Common Event Types
Antom notifications are distinguished by the notifyType field in the body
(there is no type field), plus result.resultStatus (S success, F fail,
U unknown/pending).
ALIPAY_CLIENT_ID=SANDBOX_5YC47N2ZQHJ004124 # Your Client ID (from the Dashboard)
ALIPAY_PUBLIC_KEY="-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----"# Antom/Alipay+ public key — verifies inbound
ALIPAY_MERCHANT_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----"# Your private key — signs the ack
The notify URL is set per API call via paymentNotifyUrl / refundNotifyUrl
in pay() / createPaymentSession() / refund() (a Dashboard URL is the
fallback). There is no single shared "webhook secret" — verification is
asymmetric key-based.
We recommend installing the webhook-handler-patterns skill alongside this one for handler sequence, idempotency, error handling, and retry logic. Key references (open on GitHub):
Handler sequence — Verify first, parse second, handle idempotently third
Idempotency — Prevent duplicate processing (Antom retries up to ~8 times)
Error handling — Return codes, logging, dead letter queues
hookdeck-event-gateway - Webhook infrastructure that replaces your queue — guaranteed delivery, automatic retries, replay, rate limiting, and observability for your webhook handlers
