Skip to main content

Webhook Overview

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_readSomeone viewed a tag
tag_scanA QR code was scanned
tag_sharedA tag was shared with someone
api_key_createdAn API key was created
webhook_testTest event for verifying webhooks

Webhook Payload​

Every webhook delivery includes:

{
  "event": "tag_created",
  "timestamp": "2024-01-15T14:30:00Z",
  "webhookId": "abc123-def456-ghi789",
  "deliveryId": "del_xyz123",
  "data": {
    "tagId": "uuid-of-the-tag",
    "shortId": "a7Bx9k",
    "title": "New Product Tag",
    "readPermission": "public",
    "writePermission": "owner",
    "createdAt": "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://dktmitcptketnziahoho.supabase.co/functions/v1/api-v1/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhook",
    "events": ["tag_created", "tag_scan"],
    "description": "My First Webhook"
  }'

2. Receive Events​

Your server receives POST requests with HMAC signatures:

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);
      break;
    case 'tag_scan':
      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​