Insomnia Snap Request Plugin

A comprehensive request signing plugin for Insomnia that implements Snap authentication methods. Snap is the Indonesian bank transfer standard that requires cryptographic signing for API security. This plugin supports both asymmetric (RSA-SHA256) and symmetric (HMAC-SHA512) signing mechanisms as specified by the Snap protocol.

Overview

Snap is the standardized transaction processing gateway used by Bank Indonesia and partner banks for secure API communication. This plugin automatically handles all cryptographic signing requirements for Snap API requests.

Table of Contents

• Features
• Installation
• Configuration
• Usage
• Signing Methods
• API Reference
• Examples
• Troubleshooting

Features

1. ✅ Asymmetric Signing (RSA-SHA256) - Server-to-server authentication with RSA key pairs
2. ✅ Symmetric Signing (HMAC-SHA512) - Client-to-server authentication with shared secrets
3. ✅ Automatic Timestamp Management - UTC+7 timezone support with proper Snap format
4. ✅ Header & Environment Fallback - Flexible credential sourcing from headers or environment
5. ✅ Body Hashing - SHA256 hashing of request bodies with JSON minification
6. ✅ Automatic Headers - Manages Content-Type and signature headers automatically

Installation

1. Place this plugin in your Insomnia plugins directory:

   ~/.config/Insomnia/plugins/

2. Restart Insomnia to load the plugin

3. Verify installation by checking Plugin settings in Insomnia

Configuration

Environment Variables

Set up the following environment variables in Insomnia:

Asymmetric Signing (RSA)

client_key       = your_client_key
private_key      = your_private_key_pem_format (with \n for newlines)

Symmetric Signing (HMAC)

client_key       = your_client_key
client_secret    = your_client_secret
base_url         = https://api.example.com (base URL for relative path calculation)

Example Environment Configuration

{
  "private_key": "-----BEGIN PRIVATE KEY-----\nMIIEvQIBADANBg...\n-----END PRIVATE KEY-----",
  "client_secret": "your_snap_client_secret_key",
  "client_key": "SNAP123456",
  "base_url": "https://api.example.com"
}

Usage

Request Naming Convention

The plugin automatically routes requests based on their request name in Insomnia:

For Asymmetric Signing

Name your request with: Snap Asymmetric

Example: "Snap Asymmetric - Create Transaction"

For Symmetric Signing

Name your request with: Snap Symmetric

Example: "Snap Symmetric - Get Transaction Status"

Automatic Headers

The plugin automatically manages these headers:

| Header | Set By | Purpose | | -------------- | ----------------------- | -------------------------- | | X-Timestamp | Plugin (if not present) | Request timestamp in UTC+7 | | X-Client-Key | Plugin (if not present) | Client identifier | | X-Signature | Plugin | Cryptographic signature | | Content-Type | Plugin | Always application/json |

Signing Methods

Asymmetric Signing (RSA-SHA256)

Use Case: Server-to-server communication where private key authentication is required

Flow:

1. Get or create X-Client-Key header
2. Get or create X-Timestamp header (UTC+7 format)
3. Create signing data: {client_key}|{timestamp}
4. Sign with RSA-SHA256 using private key
5. Set X-Signature header

Example:

Data to Sign: G123456789|2025-10-23T19:32:33.818+07:00
Signature: [base64 encoded RSA-SHA256 signature]

Symmetric Signing (HMAC-SHA512)

Use Case: API authentication where access tokens and shared secrets are used

Flow:

1. Extract HTTP method (GET, POST, etc.)
2. Calculate relative URL (full URL minus base_url)
3. Get access token from Authorization header or environment
4. Get or create timestamp (UTC+7 format)
5. Generate SHA256 hash of request body (or empty string if no body)
6. Create signing data: {method}:{relativeURL}:{accessToken}:{bodyHash}:{timestamp}
7. Sign with HMAC-SHA512 using client secret
8. Set X-Signature header

Example:

String to Sign:
POST:/snap/v1/transactions:eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9:4a7e5c3d2b1f...:2025-10-23T19:32:33.818+07:00

Signature: [base64 encoded HMAC-SHA512 signature]

API Reference

Utility Functions

minifyJSON(jsonString)

Safely minifies a JSON string by parsing and re-stringifying it.

• Parameters: jsonString - JSON string to minify
• Returns: Minified JSON or original string if parsing fails
• Example: minifyJSON('{"key":"value"}') → '{"key":"value"}'

getHeaderOrEnv(request, headerName, envVarName)

Retrieves a value from request headers, with environment variable fallback.

• Parameters:
  • request - Insomnia request object
  • headerName - Header name to retrieve
  • envVarName - Environment variable fallback
• Returns: Header value or environment value
• Example: getHeaderOrEnv(req, 'X-Client-Key', 'client_key')

generateTimestamp()

Generates ISO 8601 timestamp in UTC+7 timezone.

• Returns: Timestamp string in format 2025-10-23T19:32:33.818+07:00
• Timezone: UTC+7 (Bangkok time)

ensureTimestamp(request)

Ensures X-Timestamp header exists, creating if necessary.

• Parameters: request - Insomnia request object
• Returns: Timestamp value (string)

formatPrivateKey(privateKey)

Converts escaped newline sequences to actual newlines in PEM format.

• Parameters: privateKey - Private key string with \n escapes
• Returns: Formatted private key
• Example: formatPrivateKey("-----BEGIN\nKEY-----") → proper PEM format

getAccessToken(request)

Extracts access token from Authorization header or environment.

• Parameters: request - Insomnia request object
• Returns: Access token string
• Priority: Authorization header (Bearer token) > Environment variable

getRelativeURL(request)

Calculates relative URL by removing base URL from full URL.

• Parameters: request - Insomnia request object
• Returns: Relative URL path
• Example: Full: https://api.com/snap/v1/transactions → Relative: /snap/v1/transactions

generateBodyHash(requestBody)

Generates SHA256 hash of request body.

• Parameters: requestBody - Request body text
• Returns: SHA256 hex hash
• Note: Returns hash of minified JSON or empty string if no body

Main Handlers

handleRequest(context)

Main request hook that routes to appropriate signing method.

• Parameters: context - Insomnia request context
• Routing: Based on request name containing "Snap Asymmetric" or "Snap Symmetric"

handleSnapAsymmetric(context)

Handles RSA-SHA256 asymmetric signing.

• Parameters: context - Insomnia request context
• Requirements:
  • X-Client-Key (header or environment)
  • private_key (environment)

handleSnapSymmetric(context)

Handles HMAC-SHA512 symmetric signing.

• Parameters: context - Insomnia request context
• Requirements:
  • access_token (Authorization header or environment)
  • client_secret (environment)
  • base_url (environment)

Examples

Example 1: Asymmetric Signing Request

Request Name: Snap Asymmetric - Create Transfer

Environment:

{
  "client_key": "SNAP123456",
  "private_key": "-----BEGIN PRIVATE KEY-----\nMIIEvQIBADANBg...\n-----END PRIVATE KEY-----"
}

Request:

POST https://api.example.com/transfers
Headers:
  Content-Type: application/json
  X-Client-Key: SNAP123456
  X-Timestamp: 2025-10-23T19:32:33.818+07:00
  X-Signature: [auto-generated]

Body:
{
  "account_number": "1234567890",
  "amount": 100000,
  "description": "Payment for order #123"
}

Example 2: Symmetric Signing Request

Request Name: Snap Symmetric - Check Transfer Status

Environment:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "client_secret": "snap_client_secret_abc123",
  "base_url": "https://api.example.com"
}

Request:

GET https://api.example.com/transfers/SNAP-TXN-20251023-001/status
Headers:
  Content-Type: application/json
  Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
  X-Timestamp: 2025-10-23T19:32:33.818+07:00
  X-Signature: [auto-generated]

Console Output:

String to Sign: GET:/snap/v1/transfers/SNAP-TXN-20251023-001/status:eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855:2025-10-23T19:32:33.818+07:00

Example 3: Request with POST Body (Symmetric)

Request Name: Snap Symmetric - Confirm Transfer

Body:

{
  "status": "completed",
  "notes": "Updated"
}

Console Output:

String to Sign: POST:/snap/v1/transactions/order-123:eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9:a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6:2025-10-23T19:32:33.818+07:00

Troubleshooting

Issue: X-Signature not being set

Check:

1. ✅ Request name contains "Snap Asymmetric" or "Snap Symmetric"
2. ✅ Required environment variables are set
3. ✅ Private key (for asymmetric) is in proper PEM format with \n line breaks
4. ✅ Merchant secret (for symmetric) is not empty

Issue: "Cannot find module 'crypto'"

Solution: This is a Node.js built-in module. Ensure Insomnia is running the correct Node.js version.

Issue: Invalid Signature

Debug Steps:

1. Check the "String to Sign" output in Insomnia console
2. Verify all components (method, URL, token, hash, timestamp) are correct
3. Confirm environment variables are not expired or incorrect
4. For asymmetric: Ensure private key format is correct (starts with -----BEGIN)

Issue: Body hash mismatch

Common Causes:

• Request body contains extra whitespace → Plugin minifies automatically
• Content-Type not set to application/json
• Environment variables using wrong encoding

File Structure

insomnia-plugin-snap-request/
├── main.js          # Plugin source code
├── README.md        # This documentation
└── package.json     # Package metadata

License

MIT License - Feel free to use and modify

Support

For issues or questions:

1. Check the Troubleshooting section
2. Review console output in Insomnia
3. Verify environment configuration
4. Check request naming convention

Last Updated: October 23, 2025 Version: 1.0.0