Webhooks

 
POST https://api-staging.billink.nl/v2/client/webhook-v3/secret/generate

 
{
  "billinkUsername": "your_username",
  "billinkID": "your_billink_id"
}

 
{
  "status": "success",
  "message": "Webhook V3 secret is generated successfully",
  "secret": "npHiAuRps5S+nTsDL2L663zmm9gfiP3wtmMDgbQNDLg="
}

 
POST https://api-staging.billink.nl/v2/client/webhook-v3/set

 
{
  "billinkUsername": "your_username",
  "billinkID": "your_billink_id",
  "url": "https://your-domain.com/webhook/order"
}

 
POST https://api-staging.billink.nl/v2/session/webhook-v3/set

 
{
  "billinkUsername": "your_username",
  "billinkID": "your_billink_id",
  "url": "https://your-domain.com/webhook/session"
}

 
{
  "status": "success",
  "message": "Webhook has been set"
}

POST https://api-staging.billink.nl/v2/client/webhook/disable POST https://api-staging.billink.nl/v2/client/webhook/disable

POST https://api-staging.billink.nl/v2/session/webhook/disable POST https://api-staging.billink.nl/v2/session/webhook/disable

 
{
  "billinkUsername": "your_username",
  "billinkID": "your_billink_id"
}

 
<?php
$secret = 'npHiAuRps5S+nTsDL2L663zmm9gfiP3wtmMDgbQNDLg='; // from Step 1

// Read RAW body — do NOT use $_POST or json_decode before verification
$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_BILLINK_SIGNATURE'] ?? '';
$timestamp = $_SERVER['HTTP_X_BILLINK_TIMESTAMP'] ?? '';

// 1. Reject requests older than 5 minutes (replay protection)
if (abs(time() - (int)$timestamp) > 300) {
    http_response_code(403);
    exit('Timestamp too old');
}

// 2. Verify signature
$expected = hash_hmac('sha256', $timestamp . $payload, $secret);

if (!hash_equals($expected, $signature)) {
    http_response_code(403);
    exit('Invalid signature');
}

// 3. Webhook verified — now you can parse
$event = json_decode($payload, true);
http_response_code(200);

 
const crypto = require('crypto');
const express = require('express');

const app = express();
const SECRET = 'npHiAuRps5S+nTsDL2L663zmm9gfiP3wtmMDgbQNDLg=';

// IMPORTANT: use express.raw — NOT express.json() —
// so req.body is a Buffer with the original bytes.
app.post('/webhook/order',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const signature = req.headers['x-billink-signature'] || '';
    const timestamp = req.headers['x-billink-timestamp'] || '';

    // 1. Replay protection
    if (Math.abs(Date.now() / 1000 - parseInt(timestamp, 10)) > 300) {
      return res.status(403).send('Timestamp too old');
    }

    // 2. Verify signature against RAW body bytes
    const rawBody = req.body.toString('utf8');
    const expected = crypto
      .createHmac('sha256', SECRET)
      .update(timestamp + rawBody)
      .digest('hex');

    const sigBuf = Buffer.from(signature, 'utf8');
    const expBuf = Buffer.from(expected, 'utf8');
    if (sigBuf.length !== expBuf.length ||
        !crypto.timingSafeEqual(sigBuf, expBuf)) {
      return res.status(403).send('Invalid signature');
    }

    // 3. Parse only after verification
    const event = JSON.parse(rawBody);
    res.status(200).end();
  }
);

app.listen(3000);

 
import hmac, hashlib, time, json

SECRET = 'npHiAuRps5S+nTsDL2L663zmm9gfiP3wtmMDgbQNDLg='

def verify_billink_webhook(raw_body: str, headers: dict, secret: str):
    signature = headers.get('X-Billink-Signature', '')
    timestamp = headers.get('X-Billink-Timestamp', '')

    # 1. Replay protection
    if abs(time.time() - int(timestamp)) > 300:
        raise ValueError('Timestamp too old')

    # 2. Verify signature
    expected = hmac.new(
        secret.encode(),
        f'{timestamp}{raw_body}'.encode(),
        hashlib.sha256
    ).hexdigest()

    if not hmac.compare_digest(expected, signature):
        raise ValueError('Invalid signature')

 
from flask import Flask, request, abort
app = Flask(__name__)

@app.post('/webhook/order')
def webhook():
    raw_body = request.get_data(as_text=True)  # RAW body, not request.json
    try:
        verify_billink_webhook(raw_body, dict(request.headers), SECRET)
    except ValueError as e:
        abort(403, str(e))
    event = json.loads(raw_body)
    return '', 200

 
from fastapi import FastAPI, Request, HTTPException
app = FastAPI()

@app.post('/webhook/order')
async def webhook(request: Request):
    raw_body = (await request.body()).decode('utf-8')  # RAW body
    try:
        verify_billink_webhook(raw_body, dict(request.headers), SECRET)
    except ValueError as e:
        raise HTTPException(status_code=403, detail=str(e))
    event = json.loads(raw_body)
    return {}

 
{
  "order_id": 12345,
  "invoice_number": "INV-2026-001",
  "invoice_number_clean": "INV2026001",
  "workflow_id": 67,
  "event": "order_paid",
  "timestamp": "2026-04-07 10:00:00"
}

 
{
  "transactionId": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "billinkInvoiceNumber": "INV-2026-001",
  "invoiceNumber": "ORDER-2026-001",
  "status": "order_created"
}