Seamless API Guide

This guide provides technical details for implementing the Seamless API webhook endpoint. For business context and integration flow, see the Seamless Integration Overview.

The Seamless API uses webhooks to send real-time game events from the API provider to your platform. Your webhook endpoint receives encrypted event notifications and responds with updated balance information.

---

Webhook Configuration

You need to provide a single webhook endpoint URL that handles all event types.

Tip

Use a Generic Webhook Endpoint

Configure one HTTP endpoint (e.g., https://yourdomain.com/webhook) to receive all event types. The event type is identified by the event_type field in the payload.

Required Information

• DOWINN will provide you with:
• API-Key - Used for AES-256 encryption/decryption
• Api-Id - Your unique platform identifier

---

Webhook Specification

Request Details

All events from DOWINN are sent as:

• Method: POST
• Content-Type: text/plain
• Body: AES-256-ECB encrypted payload

Payload Structure

Raw Payload Request Example from the API provider

• Method: POST

Header

{
  "Content-Type": "text/plain",
  "Api-Id": "Api-Id Provided",
  "Api-Key": "Api-Key Provided"
}

Body

{
  "transaction_id": "0_sandboxagent01_1763107509159_5036",
  "event_type": "login",
  "timestamp": 1763107509,
  "feedback_data": "TEST_FEEDBACK_DATA",
  "user_id": "edwincalma"
}

Raw Payload Response Example to DOWINN

• HTTP Status: 200

Header

{
  "Content-Type": "text/plain",
  "Api-Id": "Api-Id Provided",
  "Api-Key": "Api-Key Provided"
}

Body

{
  "code": "R0", // Required, String
  "event_type": "login", // Required, String
  "timestamp": 1763107693, // Required, Number
  "user_id": "edwincalma", // Required, String
  "latest_balance": 1111000 // Required, Number
}

Note

The event_type field determines which event type was sent. Your webhook must handle all event types.

---

Response Requirements

Caution

Critical Requirements

• Api-Key and Api-Id in response headers must always be the same as in the request.
• HTTP Status: Always return 200 OK for successfully processed events
• Code: Must be one of the defined response codes (e.g., "R0" for success)
• Content-Type: text/plain
• Body: Encrypted JSON response (matching event type)
• Encryption: Use the same Api Key and Api Id provided by the API provider

Sample Error Codes

• Success Processing = "R0"
• Failed Processing = "R1"
• Unauthorized Request = "R2"
• Validation Failed = "R3"
• Not Enough Balance = "R4"

Error Responses

Even for errors (insufficient balance, invalid player, etc.), return 200 OK with an encrypted error response:

Sample Error Response

{
  "code": "R1", // Required, String
  "event_type": "logout", // Required, String
  "timestamp": 1763107508, // Required, Number
  "user_id": "edwincalma", // Required, String
  "latest_balance": 1111000 // OPTIONAL, Number
}

---

Event Types Summary

Your webhook must handle these event types:

Each event type has specific request/response schemas. See individual event documentation:

• Login Event - Authenticate player and return current balance
• Bet Event - Deduct bet amount from balance
• Bet Cancel Event - Refund a previously placed bet
• Result Event - Credit winnings to balance
• Result Change Event - Adjust balance due to result correction
• Logout Event - End player session
• Failed Notification - Handle failed webhook notifications

RESTful API used

• Webhook History - View webhook call history for debugging and audit

---

Encryption Specification

All webhook requests and responses use AES encryption:

• Algorithm: AES (Advanced Encryption Standard)
• Key Size: 256 bits
• Mode: ECB (Electronic Codebook)
• Padding: PKCS#7 (PKCS5)
• Encoding: Base64 (for encrypted payload)

Encryption Flow

For detailed encryption implementation, see the Encryption Guide.

---

Implementation Example

Below is a complete Express.js implementation showing how to receive and process webhook events:

index.js

const express = require('express')
const app = express()
const { encrypt, decrypt } = require('./utils');

const PORT = 3000
const API_KEY = ''

app.use(express.text({ type: 'text/plain' }))

app.post('/endpoint_url', (req, res) => {
  const plainText = req.body
  const decryptedData = decrypt(plainText, API_KEY)
  // Process the webhook here...
  // Encrypt the raw data...
  const encryptedData = encrypt(rawResponse, API_KEY)
  // The response status must be HTTP 200 OK
  return res.status(200).json(encryptedData)
})

app.listen(PORT, () => {
  console.log(`Server running on http://localhost:${PORT}`)
})

utils.js

const crypto = require('crypto')

function encrypt(plainText, encryptionKey) {
  try {
    const cipher = crypto.createCipheriv(
      'aes-256-ecb',
      Buffer.from(encryptionKey),
      null
    )
    cipher.setAutoPadding(true)
    let encryptedData = cipher.update(plainText, 'utf8', 'base64')
    encryptedData += cipher.final('base64')
    return encryptedData
  } catch (error) {
    return null
  }
}

function decrypt(encryptedData, encryptionKey) {
  try {
    const decipher = crypto.createDecipheriv(
      'aes-256-ecb',
      Buffer.from(encryptionKey),
      null
    )
    decipher.setAutoPadding(true)
    let decryptedData = decipher.update(encryptedData, 'base64', 'utf8')
    decryptedData += decipher.final('utf8')
    return decryptedData
  } catch (error) {
    return null
  }
}

module.exports = { encrypt, decrypt }

---

Next Steps

1. Review Seamless Integration Overview
2. Implement Encryption utilities
3. Start with Login Event implementation