Authenticatie (Authentication)

Elk verzoek aan de Partner API moet worden geauthenticeerd met HMAC-SHA256-verzoekondertekening (request signing). Dit zorgt ervoor dat verzoeken zowel authentiek zijn als niet zijn gemanipuleerd tijdens het transport.

Vereiste headers

Handtekeningconstructie

De handtekening (signature) wordt berekend door een punt-gescheiden berichtreeks samen te stellen en deze te ondertekenen met uw API-sleutelgeheim:

message = "{timestamp}.{nonce}.{method}.{path}.{body}"
signature = HMAC-SHA256(apiKeySecret, message).hexDigest()

De berichtcomponenten, samengevoegd met punten (.):

1. timestamp — Unix-tijdstempel in seconden (dezelfde waarde als de X-Timestamp-header)
2. nonce — Dezelfde waarde als verzonden in de X-Nonce-header
3. method — De HTTP-methode in hoofdletters (bijv. GET, POST)
4. path — Het volledige verzoekpad (bijv. /v2/partners/products/tickets)
5. body — De onbewerkte JSON-verzoektekst. Voor GET-verzoeken zonder body, gebruik een lege tekenreeks ""

De resulterende HMAC-digest moet worden gecodeerd als kleine letters hex.

Voorbeelden

API_KEY="your-api-key"
API_SECRET="your-api-secret"

# Signing key = SHA-256 hex digest of your API secret (as an ASCII string)
# $NF, not $2: OpenSSL prints "SHA2-256(stdin)= <hash>" but LibreSSL (the macOS
# default) prints the bare hash, where $2 is empty — that yields an empty signing
# key and a 401 with nothing to indicate why.
SIGNING_KEY=$(echo -n "${API_SECRET}" | openssl dgst -sha256 | awk '{print $NF}')

TIMESTAMP=$(date +%s)
NONCE=$(uuidgen | tr '[:upper:]' '[:lower:]')
METHOD="POST"
REQ_PATH="/v2/partners/webhooks"

# Compact JSON, no whitespace. Sign the exact string you send.
BODY='{"url":"https://yourapp.com/webhooks/vignetim","events":["order.completed"]}'

MESSAGE="${TIMESTAMP}.${NONCE}.${METHOD}.${REQ_PATH}.${BODY}"

SIGNATURE=$(echo -n "${MESSAGE}" | \
  openssl dgst -sha256 -hmac "${SIGNING_KEY}" | \
  awk '{print $NF}')

curl -X POST "https://api.vignetim.com${REQ_PATH}" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ${API_KEY}" \
  -H "X-Timestamp: ${TIMESTAMP}" \
  -H "X-Nonce: ${NONCE}" \
  -H "X-Signature: ${SIGNATURE}" \
  -d "${BODY}"

Belangrijke opmerkingen

• De X-Timestamp moet binnen 5 minuten (300 seconden) van de servertijd liggen. Verzoeken met verouderde tijdstempels worden geweigerd met een 401-fout.
• Elke X-Nonce-waarde moet uniek zijn en kan slechts eenmaal worden gebruikt. Hergebruik van een nonce resulteert in een 401-fout.
• Gebruik altijd de onbewerkte, niet-opgemaakte JSON-body-tekenreeks voor de handtekeningberekening. Maak de body niet mooier op en serialiseer deze niet opnieuw voordat u ondertekent.
• De handtekening moet kleine letters hex-gecodeerd zijn. Gebruik geen base64.