Prokeep SNAPI API (1.0.0)

The Supplier Network API (SNAPI) provides programmatic access to Prokeep's messaging platform, enabling suppliers to integrate their systems with Prokeep's communication infrastructure. This API allows suppliers to search for customer groups, retrieve industry information, and send messages to Prokeep users.

SNAPI uses HTTP Basic Authentication with supplier-specific credentials. Each supplier partner is provided with:

• Username: A unique API username for your supplier partner account
• Password: A secure API password

All API requests must include an Authorization header with Basic authentication: The resulting header would look like this:

Authorization: Basic {base64_encoded_credentials}

Where {base64_encoded_credentials} is the Base64 encoding of username:password

# Encode credentials
$ echo -n "your_username:your_password" | base64
# Output: eW91cl91c2VybmFtZTp5b3VyX3Bhc3N3b3Jk

# Use in request
$ curl -H "Authorization: Basic eW91cl91c2VybmFtZTp5b3VyX3Bhc3N3b3Jk" \
    https://snapi.prokeep.com/v1/groups

SNAPI implements rate limiting to ensure fair usage and system stability. Contact Prokeep support for specific rate limit information for your partner account.

Suppliers can receive real-time updates about message responses through webhooks. When configuring your supplier partner account, you'll provide:

• Webhook URL: The HTTPS endpoint where Prokeep will send webhook events
• Webhook Secret: A shared secret used to verify webhook authenticity

All webhooks include an HMAC signature in the X-Prokeep-Signature header for verification:

# Verify webhook signature (example in Javascript)
const crypto = require('crypto');

/**
 * Verifies SNAPI webhook signature according to official specification
 *
 * @param {string} payload - The raw request body as a string
 * @param {string} signature - The X-Prokeep-Signature header value
 * @param {string} timestamp - The X-Timestamp header value
 * @param {string} secret - Your webhook secret from Prokeep
 * @returns {boolean} - True if signature is valid, false otherwise
 */
function verifyWebhookSignature(payload, signature, timestamp, secret) {
    if (!signature || !timestamp) {
        return false;
    }

    // Remove sha256= prefix if present
    const cleanSignature = signature.startsWith('sha256=') ? signature.slice(7) : signature;

    // Create message: timestamp + "." + request_body
    const message = timestamp + '.' + payload;

    // Calculate HMAC-SHA256
    const expectedSignature = crypto
        .createHmac('sha256', secret)
        .update(message, 'utf8')
        .digest('hex');

    // Use timing-safe comparison to prevent timing attacks
    return crypto.timingSafeEqual(
        Buffer.from(cleanSignature, 'hex'),
        Buffer.from(expectedSignature, 'hex')
    );
}

// Example usage:
const payload = '{"event":"message.reply","data":{...}}';
const timestamp = req.get('X-Timestamp');          // e.g., "1642253400"

// Check both possible signature headers (one or the other will exist)
const prokeepSignature = req.get('X-Prokeep-Signature');
const xSignature = req.get('X-Signature');
const signature = prokeepSignature || xSignature;  // e.g., "sha256=abc123def456..."

const secret = 'your_webhook_secret_here';
const isValid = verifyWebhookSignature(payload, signature, timestamp, secret);

1. Rate Limiting: Implement exponential backoff when encountering rate limits
2. Pagination: Always handle pagination for large result sets
3. Error Handling: Implement robust error handling for all API calls
4. Caching: Cache industry and group data when appropriate to reduce API calls
5. Webhook Verification: Always verify webhook signatures before processing
6. Idempotency: Use unique identifiers for contacts to ensure message consistency
7. Monitoring: Log all API interactions for debugging and audit purposes
8. Attachment Validation: Ensure attachment URLs are publicly accessible and stable
9. Contact Information: Provide either email or phone number for all contacts
10. Group Validation: Verify groups accept supplier messages before sending