On this page

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#

EventSent whenFetch with
application.receivedVector accepts an applicationGET /api/v1/applications/{application_id}
decision.readyAn application reaches a final decisionGET /api/v1/applications/{application_id}
application.cancelledAn application is cancelledGET /api/v1/applications/{application_id}
repayment.recordedA repayment is recorded on an applicationGET /api/v1/applications/{application_id}
statement_read.completedA statement read finishesGET /api/v1/statement-reads/{statement_read_id}
statement_read.failedA statement read can’t be completedGET /api/v1/statement-reads/{statement_read_id}

Payload#

Every event is a POST with a JSON body in this envelope:

json
{
  "event": "decision.ready",
  "event_id": "evt_01KAXXXXXXXXXXXXXXXXXXXXXX",
  "application_id": "APPLICATION_ID",
  "created_at": "2026-11-20T12:58:24.000Z",
  "data": { }
}
FieldDescription
eventThe event type.
event_idUnique ID for this event. It stays the same across retries.
application_idThe application the event belongs to. Left out for statement reads.
created_atWhen the event happened, in ISO 8601 UTC.
dataEvent 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:

json
{
  "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:

json
"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.

js
// 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
# 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
// 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.