Ripple Collections (0.1.0)

API environments

The Ripple Collection APIs offers the following environments:

API authentication

All API operations in UAT and Production require a Bearer access token specific to the environment you're using. Ripple provides a secure model for authentication and authorization by providing access tokens scoped for a set of credentials.

Generate client ID and client secret

You will need your client ID and client secret to obtain an access token. If you do not already have your client ID and client secret, do the following:

1. Log into the Ripple Collections UI. 2. In the left navigation menu, click Settings. 3. Under Administration, click API Credentials. 4. In the dropdown list next to the page title, select the access environment. For example, to provision credentials for the test environment, select Test from the dropdown list. 5. In the upper right corner of the page, click New Credential. 6. Click Save and Generate Key. Caution: The client secret is displayed only once when you are creating new credentials. You cannot retrieve the secret after exiting this page. Copy and store the client secret securely and share it with authorized individuals in accordance with your organization's security policy. You can now use the client ID and client secret to generate access tokens using the Request an access token operation.

Request an access token

To get an access token, use the Request an access token operation with your client_id and client_secret. The response contains a token in the access_token field. We recommend rotating your API credentials at regular intervals according to your organization's security policy. Note: Authentication tokens are not a fixed length and can vary, avoid validating tokens based on character length.

Idempotency

When a client supplies a unique key (X-Idempotency-Key, UUID). The header is optional: if it is omitted the request is processed normally (no deduplication, no replay). Supplying the header is strongly recommended for POST operations that create side effects. Provide optional X-Idempotency-Key on POST writes for safe retries:

• Success → cached and replayable.
• In-flight duplicate → 409 (retry later).
• Mismatch → 422.
• Failure → entry removed (safe retry).
• Only successes are replayed.

With vs Without the Header

With X-Idempotency-Key:

• First request claims and (if successful) caches response.
• Concurrent duplicates while in flight receive 409 + Retry-After: 1.
• Later identical retries get the cached 2xx response.
• Different payload/path/method using same key → 422 mismatch.

Without the header:

• Filter bypasses idempotency entirely.
• Each call executes independently; duplicates may create repeated side effects.

Verifying Webhooks

When receiving webhooks, the signing operation has already been performed by the platform and you must validate the signature we provide to ensure the webhook originated from us. When creating a subscription (using the subscription API), you are provided a signature_verification_key. This value is a base64‑encoded symmetric secret used to compute an HMAC-SHA256 signature for each webhook payload. You must persist this secret securely at subscription creation time.

NOTE: The returned signature_verification_key is base64-encoded binary. In the code sample below we base64‑decode it to raw bytes (you do NOT re‑encode it). You may display it in hex for debugging, but hex is not required for verification. When a webhook is dispatched:

• We include X-Webhook-Timestamp (epoch milliseconds).
• We include X-Webhook-Signature in the form: t=<timestamp>,v1=<hex_hmac_sha256>.
• You reconstruct the exact signing string and verify.

Verification is a 2 step process:

Fields Used in the Signature

If any of these values are transformed (e.g. JSON pretty-printed, numeric formatting changed, timestamp altered) the verification will fail.

Verification Example

Flask Usage Example

Key Points

• Always read raw bytes first; only parse JSON after verification.
• Do not pretty-print or modify the JSON before hashing.
• Reject if age window exceeded or headers malformed.
• Use hmac.compare_digest for constant-time comparison.

Common Pitfalls

Checklist

• Captured raw body (not parsed then re-stringified)
• Extracted X-Webhook-Timestamp
• Parsed X-Webhook-Signature → t & v1
• Computed SHA256 hex of raw body
• Built signing string <timestamp>.<body_hash>
• Base64-decoded stored secret
• HMAC-SHA256 computed & constant-time compared
• (Optional) Freshness window passed

If every box is checked and comparison succeeds, the webhook is authentic.