Receive Vector webhooks
Vector sends a webhook when something you’re waiting for happens, such as a decision being ready or a statement read finishing. Webhooks are notices: use the IDs they carry to fetch the full record from the API.
Set up an endpoint#
In Enterprise, open Settings → API Keys & Webhooks and add your endpoint URL. Add one endpoint for Test and one for Live. Each environment only sends events to its own endpoint.
Vector shows the signing secret (whsec_…) once. Store it with your API keys. If you lose it, rotate it from the same page; the old secret stops working straight away.
Endpoint URLs must be public HTTPS addresses. Vector doesn’t follow redirects.
Events#
| Event | Sent when | Fetch with |
|---|---|---|
application.received | Vector accepts an application | GET /api/v1/applications/{application_id} |
decision.ready | An application reaches a final decision | GET /api/v1/applications/{application_id} |
application.cancelled | An application is cancelled | GET /api/v1/applications/{application_id} |
repayment.recorded | A repayment is recorded on an application | GET /api/v1/applications/{application_id} |
statement_read.completed | A statement read finishes | GET /api/v1/statement-reads/{statement_read_id} |
statement_read.failed | A statement read can’t be completed | GET /api/v1/statement-reads/{statement_read_id} |
Payload#
Every event is a POST with a JSON body in this envelope:
{
"event": "decision.ready",
"event_id": "evt_01KAXXXXXXXXXXXXXXXXXXXXXX",
"application_id": "APPLICATION_ID",
"created_at": "2026-11-20T12:58:24.000Z",
"data": { }
}| Field | Description |
|---|---|
event | The event type. |
event_id | Unique ID for this event. It stays the same across retries. |
application_id | The application the event belongs to. Left out for statement reads. |
created_at | When the event happened, in ISO 8601 UTC. |
data | Event details, described below. |
decision.ready: data is the same as the response from GET /api/v1/applications/{application_id}.
application.cancelled: data has reason and cancelled_at.
statement_read.completed:
{
"event": "statement_read.completed",
"event_id": "evt_01KAXXXXXXXXXXXXXXXXXXXXXX",
"created_at": "2026-11-20T12:58:24.000Z",
"data": {
"statement_read_id": "STATEMENT_READ_ID",
"reference": "read-demo-001",
"status": "completed",
"accounts": [
{
"accountNumber": "0000000001",
"bankName": "Yana Test Bank",
"transactionCount": 21,
"period": { "from": "2026-08-01", "to": "2026-10-31" }
}
]
}
}statement_read.failed: has "status": "failed" and a failure in place of accounts:
"data": {
"statement_read_id": "STATEMENT_READ_ID",
"reference": "read-demo-001",
"status": "failed",
"failure": { "code": "STATEMENT_NAME_MISMATCH", "message": "..." }
}Verify the signature#
Each request has an x-vector-signature header. Its value is a lowercase hex HMAC-SHA256 of the raw request body, using your signing secret as the key. Use the whole secret, including the whsec_ prefix.
Compute the HMAC over the raw body before you parse the JSON, and compare it in constant time. Reject the request if they don’t match.
// Node.js (Express: use express.raw({ type: 'application/json' }) on this route)
const crypto = require('crypto');
function isFromVector(rawBody, signature) {
const expected = crypto
.createHmac('sha256', process.env.VECTOR_WEBHOOK_SECRET)
.update(rawBody)
.digest('hex');
return typeof signature === 'string'
&& signature.length === expected.length
&& crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}# Python
import hmac, hashlib, os
def is_from_vector(raw_body: bytes, signature: str) -> bool:
expected = hmac.new(os.environ["VECTOR_WEBHOOK_SECRET"].encode(), raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, signature or "")// PHP
$expected = hash_hmac('sha256', file_get_contents('php://input'), getenv('VECTOR_WEBHOOK_SECRET'));
$valid = hash_equals($expected, $_SERVER['HTTP_X_VECTOR_SIGNATURE'] ?? '');Respond and retry#
Return any 2xx status within 10 seconds. Do slow work after you respond.
If your endpoint returns any other status, times out or can’t be reached, Vector retries after 1 minute, 5 minutes, 30 minutes, 2 hours and 6 hours. After 6 failed attempts in total, Vector stops retrying that event.
The same event can arrive more than once. Store event_id and ignore events you’ve already handled.
Test your endpoint#
With your test key, submit a test statement or an application with a test BVN. Your Test endpoint receives the events within a few seconds.