Skip to main content

Webhook Overview

Coming Soon

Webhooks are currently in development and will be available soon. This documentation describes the planned functionality.

Webhooks let your applications receive real-time notifications when events happen in tagd-ai. Instead of polling for changes, tagd-ai pushes updates to your server as they occur.

What Are Webhooks?​

Webhooks are HTTP callbacks:

  1. You provide a URL endpoint on your server
  2. When an event occurs, tagd-ai sends an HTTP POST to your URL
  3. Your server processes the event and responds
  4. All in real-time

How They Work​

┌─────────┐         ┌─────────┐         ┌──────────────┐
│  User   │ ──────▶ │  tagd-ai   │ ──────▶ │  Your Server │
│ Actions │         │ Server  │         │  (Webhook)   │
└─────────┘         └─────────┘         └──────────────┘
                          │
                    Event occurs
                          │
                          ▼
                   POST to your URL
                   with event data

Available Events​

EventDescription
tag.createdA new tag was created
tag.updatedTag content was modified
tag.deletedA tag was deleted
tag.viewedSomeone viewed a tag
qr.scannedA QR code was scanned
qr.generatedA QR code was generated
file.uploadedA file was uploaded to a tag
file.deletedA file was removed

Webhook Payload​

Every webhook delivery includes:

{
  "id": "evt_abc123xyz",
  "event": "tag.created",
  "created_at": "2024-01-15T14:30:00Z",
  "data": {
    "tag": {
      "id": "tag_123",
      "short_id": "a7Bx9k",
      "title": "New Product Tag",
      "created_at": "2024-01-15T14:30:00Z"
    }
  }
}

Use Cases​

Sync with External Systems​

  • Update your CRM when tags are created
  • Sync tag data to your database
  • Trigger workflows in other applications

Analytics and Monitoring​

  • Track QR code scans in real-time
  • Build custom dashboards
  • Monitor tag engagement

Automation​

  • Send notifications when tags are viewed
  • Trigger actions based on tag events
  • Automate content updates

Security and Auditing​

  • Log all tag access
  • Alert on suspicious activity
  • Maintain audit trails

Requirements​

Plan Requirements​

PlanWebhooks Allowed
Free0
Pro5
EnterpriseUnlimited

Technical Requirements​

Your webhook endpoint must:

  • Be accessible via HTTPS
  • Respond within 30 seconds
  • Return 2xx status for success
  • Accept POST requests with JSON body

Quick Start​

1. Create a Webhook​

curl -X POST https://api.tagd-ai.com/v1/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My First Webhook",
    "url": "https://your-server.com/webhook",
    "events": ["tag.created", "qr.scanned"]
  }'

2. Receive Events​

Your server receives POST requests:

app.post('/webhook', (req, res) => {
  const { event, data } = req.body;
  console.log(`Event: ${event}`, data);
  res.sendStatus(200);
});

3. Process Events​

Handle different event types:

app.post('/webhook', (req, res) => {
  switch (req.body.event) {
    case 'tag.created':
      handleNewTag(req.body.data.tag);
      break;
    case 'qr.scanned':
      logScan(req.body.data);
      break;
  }
  res.sendStatus(200);
});

Delivery Guarantees​

At-Least-Once Delivery​

  • tagd-ai guarantees delivery at least once
  • Events may occasionally be delivered multiple times
  • Use event ID for deduplication

Retry Policy​

If your endpoint fails:

  • Retry 1: 1 minute after failure
  • Retry 2: 5 minutes
  • Retry 3: 30 minutes
  • Retry 4: 2 hours
  • Retry 5: 24 hours

After 5 failures, webhook is disabled.

Event Ordering​

  • Events generally arrive in order
  • High-volume events may arrive out of order
  • Use timestamps for ordering if needed

Next Steps​