> ## Documentation Index
> Fetch the complete documentation index at: https://vas-partner-api-docs.finpaytech.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Receive Payment Paid Events on Your HTTPS Endpoint

Register a URL. After a successful inbound credit is stored, Emaal `POST`s `payment.paid` to every active endpoint.

## Register

```http theme={null}
POST https://vas.finpaytech.co/business-api/api/v1/merchants/me/webhook-endpoints
Authorization: Bearer <access-token>
Content-Type: application/json

{
  "url": "https://partner.example.com/webhooks/emaal",
  "description": "Production collections"
}
```

The **secret is returned once**. Store it. Later `GET` calls omit `secret`.

URL must be `https://` (or `http://localhost` / `http://127.0.0.1` for development).

## List and Deactivate

```http theme={null}
GET https://vas.finpaytech.co/business-api/api/v1/merchants/me/webhook-endpoints
POST https://vas.finpaytech.co/business-api/api/v1/merchants/me/webhook-endpoints/{endpointId}/deactivate
```

## Event Envelope

Headers:

* `Content-Type: application/json`
* `X-Emaal-Event: payment.paid`
* `X-Emaal-Delivery: <delivery-id>`
* `X-Emaal-Signature: sha256=<hex>`

Body:

```json theme={null}
{
  "id": "5e8b3c1a-2d44-4f0e-9c11-0a1b2c3d4e5f",
  "type": "payment.paid",
  "createdAt": "2026-09-09T07:52:21.200Z",
  "data": {
    "paymentId": "70d9370e-62ad-4b97-a024-862feee88541",
    "merchantId": "301f0991-8f7c-4501-a1d4-c317fe7b7f23",
    "subMerchantId": null,
    "expectedPaymentId": "721e86a8-fd29-49b5-b42f-67e19dfb2f6e",
    "paymentReference": "INV-2026-1044",
    "amount": 130.00,
    "currency": "KES",
    "virtualAccountId": "9d6be39e-9465-4d67-a05a-4b366352bd64",
    "attributionStatus": "ATTRIBUTED",
    "attributionMethod": "INVOICE_VA",
    "receiptId": null,
    "receiptNumber": null,
    "creditedAt": "2026-09-08T16:52:08.000Z"
  }
}
```

Respond **2xx** quickly. Fetch the full payment with `GET https://vas.finpaytech.co/business-api/api/v1/merchants/me/payments/{paymentId}` if you need payer narration or originator details.

## Verify Signature

`X-Emaal-Signature` is `sha256=` plus the hex HMAC-SHA256 of the **raw JSON body** using the endpoint secret.

```python theme={null}
import hashlib
import hmac

def valid(secret: str, raw_body: bytes, header: str) -> bool:
    expected = "sha256=" + hmac.new(
        secret.encode(), raw_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, header)
```