Set Webhook URL | VTUAgent

Registers the HTTPS endpoint that receives transaction notifications. One URL per account; calling again replaces it.

Delivery

We POST a JSON body to your URL with a 10-second timeout. There are no retries and no Authorization header — verify the hash field instead: hash = hex( SHA-256( "<your_api_key>:<reference>" ) ). Compare with constant-time equality and respond 200 promptly.

The body always has exactly eight keys — event, reference, status, amount, product_type, details, hash, timestamp — see the WebhookPayload schema for the exact body.

`event`	Sent by	When
`airtime.purchase.success`	`/v1/airtime/purchase`	Provider confirmed delivery
`airtime.purchase.failed`	`/v1/airtime/purchase`	Provider rejected or was unreachable — wallet refunded
`airtime.purchase.pending`	`/v1/airtime/purchase`	Provider still processing
`data.purchase.success`	`/v1/data/purchase`	Provider confirmed delivery
`data.purchase.failed`	`/v1/data/purchase`	Provider rejected — wallet refunded
`transaction.requery`	`/v1/transaction/status`	Every call to the status endpoint; `status` mirrors the stored transaction

Cable TV and electricity purchases do not emit webhooks — rely on the synchronous response or /v1/transaction/status.

Authentication

AuthorizationBearer

API key issued from the VTUAgent dashboard, sent as Authorization: Bearer {your_api_key}.

Request

This endpoint expects an object.

webhook_urlstringRequiredformat: "uri"

Absolute URL.

Response

Webhook URL saved

statusenumOptional

Allowed values:

messagestringOptional

dataobjectOptional

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

500

Internal Server Error