Signature Validation

Description

Rakuten CPaaS signs all HTTP requests from its servers to your application server, and assembles the request to your application server by concatenating the final request URL (the full URL with the scheme, port, and query string) and any POST parameters and generating a signature as per steps defined below.

When receiving, the incoming webhook from Rakuten CPaaS will include the signature and all the fields you need to generate the signature in your application to verify that the two signatures match. Use the other parameters in the request with your SIGNATURE_SECRET to generate the signature and compare it to the signature that was sent. If the two match, the request is valid.

The SIGNATURE_SECRET is different from your PASSWORD and will be provided by your account manager.

These are the steps to be followed for generating the signature and validating against the one received in the headers

Step 1: Request Method

Get the HTTP request method, such as GET, PUT, HEAD, and DELETE

Step 2: Header Verification

Check presence of all required headers

Parameter	Description
host	This is the webhook domain e.g., api.cpaas.symphomy.rakuten.net
x-api-signature-algorithm	Supported algorithm - hmac-sha256 - hmac-sha512
x-api-signature-version	Default: 1.0
x-api-signature-keyid	Default: 2
x-security-signature-timestamp	The current timestamp (UTC) in format = YYYY-MM-DD HH:mm:ss e.g., 2025-03-13 12:24:14
x-api-nonce	Pseudorandom number e.g., sbXrFfa1zyrAC5huBeIqKi86tOPrg8ffOw
x-api-payload-digest	Will be populated if payload is present
x-api-signature	Signature in HEX

Step 3: Request Path

Get the request path from the full URL path e.g., /v1/resources

Step 4: Query String

Get the URL parameters without "?". It will be an empty string if no parameters e.g., param1=value1&param2=value2

Step 5: Timestamp Validation

1. Parse timestamp from X-Security-Signature-Timestamp
2. Calculate time difference from current server time
3. Reject if difference exceeds 5 minutes
4. Consider time zone differences and clock synchronization

Step 6: Payload Digest Validation

1. Read HTTP Headers to get X-API-Payload-Digest and convert to Lower Case
2. Encode the body using SHA256 to get calculated Payload Digest
3. Convert calculated value to Lower Case
4. Compare X-API-Payload-Digest to the calculated Payload Digest

Step 7: Signature String Recreation

Reconstruct the signature string by concatenating components with ":" delimiter in the following order

1. HTTP Method (uppercase) e.g., POST
2. Host from the host header e.g., api.cpaas.symphony.rakuten.net
3. Request Path from the full URL path e.g., /v1/resources
4. Query String e.g., "param1=value1&param2=value2"
5. Payload Digest
- SHA-256 hash of payload
- Empty string if no payload
- Example: "a1b2c3d4…" 6. Algorithm from X-API-Signature-Algorithm e.g., hmac-sha256
7. Version from X-API-Signature-Version e.g., 1.0
8. Key ID from X-API-Signature-KeyId e.g., 2
9. Timestamp from X-Security-Signature-Timestamp e.g., 2025-03-11 10:00:00
10.Nonce from X-API-Nonce e.g., abc123xyz789

Important Rules:

1. Maintain exact component order
2. Use colon ":" delimiter. There is a trailing ":" at the end of the concatenated string
3. No spaces around delimiters
4. Include delimiters for empty values
5. Case-sensitive values

Format Example:

POST:api.cpaas.symphony.rakuten.net:/v1/resources:param1=value1&param2=value2:a1b2c3d4...:hmac-sha256:1.0:2:2025-03-11 10:00:00:abc123xyz789:

Step 8: Generate Signature

Encode using HMAC-SHA256 (String, Signature Key) and convert to HEX Bytes where Signature Key is the SIGNATURE_SECRET received from Rakuten CPaaS

Step 9: Validate Signature

Compare the X-API-Signature received in the headers from Rakuten CPaaS with the signature calculated above