Webhook

Webhooks allow your system to receive real-time notifications when a collection request changes state.

When the event occurs, qid sends a POST request to the configured webhook URL. Your server should receive the notification and then optionally call the API to fetch the latest data.

Webhook request


Method	`POST`
Content-Type	`application/json`

Headers

Header	Description
`X-QID-Signature`	HMAC SHA256 signature of the webhook payload
`X-QID-Timestamp`	Timestamp used when generating the signature
`X-QID-Event`	Type of event that triggered the webhook
`X-QID-Delivery-Id`	Unique ID for this webhook delivery
`User-Agent`	`qid-webhooks/1.0`

Payload

{
  "event": "collection_request.updated",
  "requestId": "65fa92f3a8b2a4a1f2e9c0a1",
  "shareStatus": "open",
  "webhookIdentifier": "hotel_checkin_123",
  "timestamp": "1710000000000"
}

Fields

Field	Description
`event`	Event type
`requestId`	Unique ID of the collection request
`shareStatus`	Current status of the share
`webhookIdentifier`	Custom identifier provided when creating the request
`timestamp`	Time when the webhook was generated

Signature verification

To ensure the webhook request originated from qid, verify the signature using the webhook secret.

Signature is generated as:

HMAC_SHA256(secret, timestamp + "." + body)

Example verification logic:

const crypto = require('crypto');

const body = JSON.stringify(payload);
const signedPayload = timestamp + '.' + body;
const expectedSignature = crypto
  .createHmac('sha256', webhookSecret)
  .update(signedPayload)
  .digest('hex');

if (expectedSignature === receivedSignature) {
  // webhook is valid
}

Recommended processing flow

Receive webhook request.
Verify X-QID-Signature.
Read the requestId.
Optionally call the API to read the collection request.

Delivery behavior

Webhooks are sent via HTTP POST
Delivery timeout: 5 seconds
Redirects are not followed
Each webhook includes a unique X-QID-Delivery-Id

Example request

curl --request POST 'https://your-server.com/webhooks/qid' \
  --header 'Content-Type: application/json' \
  --header 'X-QID-Event: collection_request.updated' \
  --header 'X-QID-Timestamp: 1710000000000' \
  --header 'X-QID-Signature: 9a83f8a2c3...' \
  --header 'X-QID-Delivery-Id: 3f2b6c1d...' \
  --header 'User-Agent: qid-webhooks/1.0' \
  --data '{
    "event": "collection_request.updated",
    "requestId": "65fa92f3a8b2a4a1f2e9c0a1",
    "shareStatus": "completed",
    "webhookIdentifier": "hotel_checkin_123",
    "timestamp": "1710000000000"
  }'