Webhooks

Webhooks allow you to receive updates about vignette sales by automatically sending data to a specified URL whenever an event occurs.

During onboarding, please provide us with the webhook URL you would like to use to receive sale reports.

Authorization

To ensure that webhook requests are secure and verifiably from us, each request includes an X-Signature header.

You can verify this signature using your Webhook Secret and the raw request payload.

import crypto from "crypto"

export function verifyWebhookSignature(receivedSignature, secret, payload) {
    const expectedSignature = crypto
        .createHmac("sha256", secret)
        .update(payload)
        .digest("hex")

    const receivedBuffer = Buffer.from(receivedSignature)
    const expectedBuffer = Buffer.from(expectedSignature)

    // Ensure both Buffers have the same length
    if (receivedBuffer.length !== expectedBuffer.length) {
        return false
    }

    // Perform constant-time comparison
    return crypto.timingSafeEqual(receivedBuffer, expectedBuffer)
}

Request

A webhook request is sent as a JSON object with the following structure:

Parameter	Description
saleId	The unique identifier of the processed sale.
vignetteId	The unique identifier of the vignette, generated after a successful activation.
vignetteSale	An object containing details about the sale (see below).

Sample webhook request payload

If the sale was successful

{
  "saleId": "string",
  "vignetteId": "string",
  "vignetteSale": {
    "success": true,
    "data": {
      "id": "string",
      "total": 0,
      "currency": "BGN",
      "totalCurrencyAmount": {
        "amountBGN": 0,
        "amountEUR": 0
      },
      "createdOn": "string",
      "active": true,
      "saleRows": [
        {
          "active": true,
          "productsResponse": {
            "id": 0,
            "vehicleType": "car",
            "validityType": "year",
            "vehicleTypeText": "Light vehicle <= 3.5t, camping vehicle M1",
            "validityTypeText": "Yearly",
            "categoryDescriptionText": "Category 3"
          },
          "id": "string",
          "email": "string",
          "addEmailUrl": "string",
          "createdOn": "string",
          "kapschProperties": {
            "id": "string",
            "product": {
              "id": 0,
              "vehicleType": "car",
              "validityType": "year"
            },
            "status": 0,
            "vehicle": {
              "lpn": "string",
              "countryCode": "string"
            },
            "validity": {
              "requestedValidityStartDate": "string",
              "validityStartDateTimeUTC": "string",
              "validityEndDateTimeUTC": "string",
              "validityEndDateTimeEET": "string",
              "validityStartDateTimeEET": "string"
            },
            "price": {
              "currency": "BGN",
              "amount": 0
            },
            "purchase": {
              "purchaseDateTimeUTC": "string"
            }
          },
          "currencyAmount": {
            "amountBGN": 0,
            "amountEUR": 0
          }
        }
      ]
    }
  }
}

If the sale failed

{
  "saleId": "string",
  "vignetteId": "string",
  "vignetteSale": {
    "success": false,
    "error": {
      "code": "string",
      "message": "string"
    }
  }
}