Callback Signature and Encryption
Introduction
This document describes the signature and encryption requirements for callback APIs (SUD OP SVR → APP server). For key configuration, algorithm parameters, calculation examples and the complete calling-direction flow, see Server API Signature and Encryption.
No additional keys are involved in the callback direction. Callback requests are verified with the SUD OpenPaaS certificate and decrypted with the symmetric key configured in Chapter 2 of Server API Signature and Encryption; callback responses are signed with the application private key and encrypted with the symmetric key.
Mandatory: Callback APIs have no plaintext mode. Every callback request must be verified and then decrypted. If either step fails, reject the request immediately without entering business logic.
I. Roles and keys
In the calling direction the APP server encrypts and signs the request, then verifies and decrypts the response; in the callback direction it is the other way round — the same key set, with the signer and verifier swapped.
| Step | Key or certificate | How the peer validates |
|---|---|---|
| Verify callback request | Public key in the SUD OpenPaaS certificate | — |
| Decrypt callback request | Symmetric key | — |
| Encrypt callback response | Symmetric key | SUD OP SVR decrypts with the symmetric key |
| Sign callback response | Application private key | SUD OP SVR verifies with the application public key |
II. Callback request processing
Process in the order verify → decrypt → business checks. If verification or decryption fails, return a non-200 status code instead of a business result.
2.1 Request headers
| Header | Required | Description |
|---|---|---|
| X-Sud-AppId | Yes | Current AppId, which must match _appid in the decrypted plaintext |
| X-Sud-Timestamp | Yes | Timestamp when the platform generated the callback request (seconds) |
| X-Sud-Signature | Yes | Platform signature, Base64 encoded |
The formula, delimiter and the way data is obtained are defined in 3.2.1 of Server API Signature and Encryption. In the callback direction only urlpath differs:
urlpathis the full URL of the callback address itself (including scheme and host, excluding the query string) and must match the value configured in the SUD OP console character by character;datais the raw bytes of the HTTP body (the ciphertext payload); never re-serialize it after parsing.
2.2 Decryption and verification
Follow Chapter 3 of Server API Signature and Encryption for decrypting and verifying the request body.
III. Signing callback responses
Responses must also be encrypted and signed; the verifier is SUD OP SVR. All signature-related response headers carry the APP server's own values.
3.1 Response headers
| Header | Required | Description |
|---|---|---|
| X-Sud-AppId | Yes | App ID |
| X-Sud-Timestamp | Yes | Timestamp when the APP server generated the response (seconds) |
| X-Sud-Serial | Yes | Application asymmetric key serial number, used by the platform to select the application public key |
| X-Sud-Signature | Yes | Signature produced with the application private key over the response payload, Base64 encoded |
| X-Sud-Serial-Deprecated | No | Application key serial number about to expire (returned during application key rotation) |
| X-Sud-Signature-Deprecated | No | Signature made with the expiring application key, Base64 encoded (returned during rotation) |
These headers share their names with open API responses but come from a different source: open API responses are signed by SUD OP SVR with the platform certificate, whereas callback responses are signed by the APP server with the application key. Do not reuse the certificate serial or the platform signature just because the names match.
3.2 Encryption and signing
Follow Chapter 3 of Server API Signature and Encryption for encrypting and signing the response body.
