Webhook Payload Documentation

Get All Transactions

Endpoint

GET /api/v1/transactions

Authentication

Requires Bearer token authentication with the transactions:read ability.

Query Parameters

Parameter	Type	Required	Description
`account_id`	integer	No	Filter by ShamCash account ID
`transaction_id`	string	No	Filter by transaction ID (partial match supported)
`date_from`	date	No	Filter transactions from this date (YYYY-MM-DD)
`time_from`	time	No	Start time when used with `date_from` (HH:MM or HH:MM:SS). Defaults to 00:00:00.
`date_to`	date	No	Filter transactions up to this date (YYYY-MM-DD, must be ≥ date_from)
`time_to`	time	No	End time when used with `date_to` (HH:MM or HH:MM:SS). Defaults to 23:59:59.
`amount_min`	numeric	No	Minimum transaction amount
`amount_max`	numeric	No	Maximum transaction amount (must be ≥ amount_min)
`username`	string	No	Filter by peer username (partial match supported)
`peer_account_address`	string	No	Filter by peer account address (partial match supported)
`currency`	string	No	Filter by currency code (e.g., SYP, USD)
`per_page`	integer	No	Number of results per page (1-100, default: 15)

Response

Returns a paginated list of transactions.

{
    "data": [
        {
            "id": 1,
            "transaction_id": "TRX-ABC123",
            "user_id": 1,
            "sham_cash_account_id": 1,
            "username": "john_doe",
            "peer_account_address": "+963912345678",
            "amount": 1500.00,
            "currency": "SYP",
            "type": "credit",
            "notes": "Payment for order ABC123",
            "date": "2024-01-15 10:30:00",
            "is_synced": true,
            "synced_by": 1,
            "created_at": "2024-01-15T10:30:00.000000Z",
            "updated_at": "2024-01-15T10:30:00.000000Z"
        }
    ],
    "links": {
        "first": "http://api.example.com/api/v1/transactions?page=1",
        "last": "http://api.example.com/api/v1/transactions?page=10",
        "prev": null,
        "next": "http://api.example.com/api/v1/transactions?page=2"
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 10,
        "links": [...],
        "path": "http://api.example.com/api/v1/transactions",
        "per_page": 15,
        "to": 15,
        "total": 150
    }
}

Example Request (cURL)

curl -X GET "https://api.example.com/api/v1/transactions?date_from=2024-01-01&time_from=09:00&date_to=2024-01-31&time_to=17:30&per_page=20" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

Configuration

Go to Webhook Settings to configure your endpoint URL and secret key. You provide your own secret key — we use it to sign payloads so you can verify they came from us.

Payload Structure

{
    "event": "transaction.created",
    "timestamp": "2024-01-15T10:30:00Z",
    "data": {
        "id": 123,
        "transaction_id": "TRX-ABC123",
        "username": "john_doe",
        "date": "2024-01-15 10:30:00",
        "amount": 1500.00,
        "currency": "SYP",
        "notes": "Payment for order ABC123",
        "created_at": "2024-01-15T10:30:00Z",
        "updated_at": "2024-01-15T10:30:00Z"
    }
}

Event Type

Event	Description
`transaction.created`	Fired when a new transaction is fetched from ShamCash

Field Descriptions

Field	Type	Description
`event`	string	The event type (always "transaction.created")
`timestamp`	string	ISO 8601 timestamp when the webhook was sent
`data.id`	integer	Internal transaction ID
`data.transaction_id`	string	ShamCash transaction ID
`data.username`	string	Peer username from ShamCash
`data.peer_account_address`	string\|null	Peer account address (e.g., phone number)
`data.date`	string	Transaction date and time
`data.amount`	float	Transaction amount
`data.currency`	string	Currency code (e.g., SYP, USD)
`data.notes`	string\|null	Transaction notes/message
`data.created_at`	string	When the record was created in our database
`data.updated_at`	string	When the record was last updated

Webhook Security

Signature Verification

Each webhook request includes a signature header. Use your configured secret key to verify the payload.

Header:

X-Webhook-Signature: t=<timestamp>,v1=<signature>

Verification Example (PHP)

// Your secret key (configured in webhook settings)
$webhookSecret = 'your-secret-key';

// Get the signature header
$signatureHeader = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';

// Get the raw payload
$payload = file_get_contents('php://input');

// Parse the signature header
// Format: t=<timestamp>,v1=<signature>
preg_match('/t=(\d+),v1=([a-f0-9]+)/', $signatureHeader, $matches);

if (count($matches) !== 3) {
    http_response_code(401);
    exit('Invalid signature format');
}

$timestamp = $matches[1];
$signature = $matches[2];

// Verify the signature
$expected = hash_hmac('sha256', $timestamp . '.' . $payload, $webhookSecret);

if (!hash_equals($expected, $signature)) {
    http_response_code(401);
    exit('Invalid signature');
}

// Process the webhook
$data = json_decode($payload, true);

Expected Response

Your endpoint should return a 2xx HTTP status code within 30 seconds to acknowledge receipt. Any other response will be considered a failure and may trigger a retry.

Success: Return HTTP 200 OK with an empty body or JSON response.

API Documentation