Webhooks
Webhooks allow external systems to notify OLIVE when events happen.VULT Cash-In Webhook
Request
| Field | Type | Description |
|---|---|---|
card_serial | string | NFC card serial |
phone_number | string | Subscriber phone (optional) |
amount | int64 | Amount to credit (> 0) |
Response
| Field | Description |
|---|---|
success | true/false |
transaction_id | Transaction ID |
message | Status message |
new_balance | Updated balance |
HMAC Verification
Header:X-Webhook-Signature
Validation Steps
- Check signature header present
- Verify HMAC matches
- Find card by serial
- Verify card status is
assigned - Verify subscriber is
active - Match phone (if provided)
Error Responses
| Error | Status | Message |
|---|---|---|
| No signature | 401 | ”Missing webhook signature” |
| Invalid signature | 401 | ”Invalid webhook signature” |
| Card not found | 400 | ”Card not found” |
| Card not assigned | 400 | ”Card not linked” |
| Wrong phone | 400 | ”Phone mismatch” |
API Keys
Partners authenticate with API keys:| Field | Description |
|---|---|
key_prefix | First 8 chars (visible) |
key_hash | SHA256 hash of full key |
hmac_secret | Per-client HMAC secret |
scopes | Allowed permissions (array) |
status | active or revoked |
rate_limit | Requests/minute (default 1000) |
ip_whitelist | Allowed IPs (array) |
VULT Transfers Table
Records funding from VULT:| Field | Type | Description |
|---|---|---|
vult_txn_id | TEXT | VULT transaction ID |
olive_subscriber_id | TEXT | Subscriber FK |
vult_wallet_id | VARCHAR(50) | VULT account |
amount | BIGINT | Amount (> 0) |
status | VARCHAR(20) | Default ‘Completed’ |