Webhooks

Webhooks allow external systems to notify OLIVE when events happen.

VULT Cash-In Webhook

POST /webhooks/vult/cashin

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

signature = HMAC-SHA256(request_body, shared_secret)

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’

Webhook API

Endpoints

Security

HMAC details

Getting Started

Agent-TS

Gateway

Wallet-Core

Concepts

Webhooks

Webhooks

VULT Cash-In Webhook

Request

Response

HMAC Verification

Validation Steps

Error Responses

API Keys

VULT Transfers Table

Webhook API

Security

​Webhooks

​VULT Cash-In Webhook

​Request

​Response

​HMAC Verification

​Validation Steps

​Error Responses

​API Keys

​VULT Transfers Table

​Related

Webhook API

Security

Webhooks

VULT Cash-In Webhook

Request

Response

HMAC Verification

Validation Steps

Error Responses

API Keys

VULT Transfers Table

Related