Setting Up Webhooks - SnapGlyph Support

Available on: Max plan only Who can manage: Owners and Admins only

What Are Webhooks?

Webhooks are HTTP callbacks that notify your server when specific events happen. Instead of polling the API to check for changes, SnapGlyph pushes updates to your endpoint instantly.

Use Cases

Real-time scan notifications: Alert your system when QR codes are scanned
Sync with external systems: Keep your database updated with QR code changes
Trigger workflows: Start automated processes based on scan events
Analytics pipelines: Feed scan data into your analytics platform

Creating a Webhook

Step 1: Go to Webhook Settings

Click Webhooks in the sidebar

Step 2: Add New Webhook

Click Create Webhook.

Step 3: Configure Endpoint

Endpoint URL: Enter the HTTPS URL where you want to receive events.

https://your-server.com/webhooks/snapglyph

Requirements:

Must use HTTPS (HTTP not allowed)
Must return a 2xx status code within 30 seconds
Should be publicly accessible

Step 4: Select Events

Choose which events trigger this webhook:

Event	Description
`qr.scanned`	A QR code was scanned
`qr.created`	A new QR code was created
`qr.updated`	A QR code was updated
`qr.deleted`	A QR code was deleted

Select all that apply to your use case.

Step 5: Save

Click Create Webhook. Your webhook is now active.

Webhook Payload

When an event occurs, SnapGlyph sends a POST request to your endpoint:

Headers

Content-Type: application/json
X-Snapglyph-Signature: sha256=abc123...
X-Snapglyph-Event: qr.scanned
X-Snapglyph-Delivery: del_xyz789

Body (qr.scanned example)

{
  "event": "qr.scanned",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "qrCodeId": "qr_abc123",
    "qrCodeName": "Product Page",
    "destinationUrl": "https://example.com/product",
    "scan": {
      "timestamp": "2024-01-15T10:30:00Z",
      "country": "US",
      "region": "California",
      "deviceType": "mobile",
      "os": "iOS",
      "browser": "Safari"
    }
  }
}

Body (qr.created example)

{
  "event": "qr.created",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "id": "qr_abc123",
    "name": "Product Page",
    "url": "https://example.com/product",
    "tracking": true,
    "createdAt": "2024-01-15T10:30:00Z"
  }
}

Verifying Webhooks

To ensure webhooks are from SnapGlyph, verify the signature:

Signature Header

X-Snapglyph-Signature: sha256=abc123def456...

Verification (Node.js example)

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return `sha256=${expected}` === signature;
}

// In your webhook handler
app.post('/webhooks/snapglyph', (req, res) => {
  const signature = req.headers['x-snapglyph-signature'];
  const isValid = verifyWebhook(
    JSON.stringify(req.body),
    signature,
    process.env.WEBHOOK_SECRET
  );

  if (!isValid) {
    return res.status(401).send('Invalid signature');
  }

  // Process the webhook
  console.log('Event:', req.body.event);
  res.status(200).send('OK');
});

Managing Webhooks

Viewing Webhooks

The Webhooks page shows all your endpoints with:

Endpoint URL
Subscribed events
Status (Active/Inactive)
Recent delivery status

Editing a Webhook

Click on the webhook you want to edit
Modify the URL or events
Click Save

Disabling a Webhook

To temporarily stop a webhook without deleting it:

Click the webhook
Toggle Active to off
Events will queue (briefly) but not deliver

Deleting a Webhook

Click the webhook
Click Delete
Confirm deletion

Testing Webhooks

Send a Test Event

Go to Webhook settings
Click Test next to your webhook
Select an event type
Click Send Test

A sample event is sent to your endpoint.

Using webhook.site

For development, use webhook.site to inspect payloads:

Go to webhook.site
Copy your unique URL
Add it as a webhook endpoint in SnapGlyph
Trigger events and see the payloads

Delivery and Retries

Successful Delivery

Your endpoint must return a 2xx status code within 30 seconds.

Failed Delivery

If delivery fails, SnapGlyph retries:

1st retry: 1 minute later
2nd retry: 5 minutes later
3rd retry: 30 minutes later
4th retry: 2 hours later
5th retry: 24 hours later

After 5 failed attempts, the webhook is marked as failing.

Viewing Delivery History

Click on a webhook
View the Delivery History section
See recent deliveries with status and response codes

Troubleshooting

Webhook not receiving events

Verify the URL is correct and accessible
Check your server logs for incoming requests
Ensure your endpoint returns 2xx quickly
Test with webhook.site to isolate the issue

Signature verification failing

Ensure you’re using the correct webhook secret
Verify you’re hashing the raw body, not parsed JSON
Check for encoding issues

Duplicate events

Events may be delivered more than once during retries
Implement idempotency using X-Snapglyph-Delivery ID
Track processed delivery IDs to skip duplicates

Timeouts

Your endpoint must respond within 30 seconds
Process webhooks asynchronously if needed
Return 200 immediately, then process in background