Delivery of an API event.

Verifying signatures

  1. Base64-decode the signature_key returned on subscription creation (standard alphabet, no = padding) to get the raw key bytes.
  2. Compute HMAC-SHA256 over the raw request body bytes exactly as received. Do not re-serialize the JSON.
  3. Hex-encode the result in lowercase (64 characters). Do not Base64-encode it.
  4. Compare it with the X-Spoton-Webhook-Signature header using a constant-time comparison.

Java (17+)

byte[] key = Base64.getDecoder().decode(signatureKey);
Mac mac = Mac.getInstance("HmacSHA256");
mac.init(new SecretKeySpec(key, "HmacSHA256"));
String expected = HexFormat.of().formatHex(mac.doFinal(rawBody));
boolean valid = MessageDigest.isEqual(
    expected.getBytes(StandardCharsets.US_ASCII),
    signatureHeader.getBytes(StandardCharsets.US_ASCII));

Node.js

const crypto = require('crypto');
const key = Buffer.from(signatureKey, 'base64');
const expected = crypto.createHmac('sha256', key).update(rawBody).digest('hex');
const valid = expected.length === signatureHeader.length &&
  crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signatureHeader));

Python

import base64, hashlib, hmac
# The key has no padding, and b64decode requires it.
key = base64.b64decode(signature_key + '=' * (-len(signature_key) % 4))
expected = hmac.new(key, raw_body, hashlib.sha256).hexdigest()
valid = hmac.compare_digest(expected, signature_header)
Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Body Params

Webhook Event

Webhook Event

string
required

Unique id of the event

date-time
required

Timestamp of the event

string
enum
required

Category of the event

string
required

Location ID

string

Organization ID that owns the location. This field is only available for onboarding events.

details
object
required

Details of the event (one of the following depending on category).

Headers
string

HMAC-SHA256 signature of the raw request body, encoded as lowercase hexadecimal (64 characters). It is not Base64-encoded.

string

Payload signature version. Currently only v1 is supported.
The v1 signature standard is an HMAC-SHA256 of the raw request body in its entirety, output as lowercase hex. The secret is the signature_key generated when the subscription is created. SpotOn shares the key Base64-encoded (standard alphabet, without = padding), so decode it to raw bytes before use.

Responses

Language
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json