> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vultlocal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Understanding how external systems notify OLIVE

# 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

1. Check signature header present
2. Verify HMAC matches
3. Find card by serial
4. Verify card status is `assigned`
5. Verify subscriber is `active`
6. 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' |

***

## Related

<CardGroup cols={2}>
  <Card title="Webhook API" icon="code" href="/api-reference/webhooks/overview">
    Endpoints
  </Card>

  <Card title="Security" icon="lock" href="/reference/security">
    HMAC details
  </Card>
</CardGroup>