Skip to main content

Setting Up Webhooks

Learn how to create and configure webhooks to receive real-time event notifications.

Creating a Webhook​

From the Dashboard​

  1. Go to Account → Webhooks
  2. Click Create Webhook
  3. Fill in the form:
    • Name: Descriptive name (e.g., "Production Events")
    • URL: Your HTTPS endpoint
    • Events: Select events to subscribe to
  4. Click Create

Via API​

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

Configuration Options​

Name​

A descriptive label for your webhook:

  • Used in the dashboard and logs
  • Doesn't affect functionality
  • Make it descriptive

URL​

Your webhook endpoint:

  • Must be HTTPS (HTTP not allowed)
  • Must be publicly accessible
  • Should respond within 30 seconds
  • Will receive POST requests

Events​

Select which events trigger the webhook:

  • Subscribe to specific events only
  • Reduces unnecessary traffic
  • Can be updated later

Secret Key​

Optional but recommended:

  • Used to verify webhook authenticity
  • You provide the secret
  • tagd-ai signs payloads with it
  • Verify signatures in your handler

Custom Headers​

Add headers to webhook requests:

  • Authentication tokens
  • Custom identifiers
  • Routing information
{
  "headers": {
    "X-Custom-Auth": "your-token",
    "X-Environment": "production"
  }
}

Setting Up Your Endpoint​

Basic Express.js Handler​

const express = require('express');
const app = express();

app.use(express.json());

app.post('/tagd-webhook', (req, res) => {
  const { event, data } = req.body;

  console.log(`Received event: ${event}`);
  console.log('Data:', JSON.stringify(data, null, 2));

  // Process the event
  processEvent(event, data);

  // Always respond with 200
  res.status(200).json({ received: true });
});

app.listen(3000, () => {
  console.log('Webhook server running on port 3000');
});

Python Flask Handler​

from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route('/tagd-webhook', methods=['POST'])
def handle_webhook():
    event = request.json.get('event')
    data = request.json.get('data')

    print(f"Received event: {event}")
    print(f"Data: {data}")

    # Process the event
    process_event(event, data)

    return jsonify({'received': True}), 200

if __name__ == '__main__':
    app.run(port=3000)

Testing Your Webhook​

Send Test Event​

From the dashboard:

  1. Go to Webhooks → select your webhook
  2. Click Send Test
  3. Choose event type
  4. View the response

Via API:

curl -X POST https://api.tagd-ai.com/v1/webhooks/{id}/test \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"event": "tag.created"}'

Test Payload​

Test events include:

{
  "id": "evt_test_123",
  "event": "tag.created",
  "test": true,
  "created_at": "2024-01-15T14:30:00Z",
  "data": {
    "tag": {
      "id": "test_tag_123",
      "short_id": "TESTID",
      "title": "Test Tag"
    }
  }
}

Local Development​

Use tunneling services for local testing:

ngrok:

ngrok http 3000
# Use the https URL as your webhook endpoint

localtunnel:

npx localtunnel --port 3000

Managing Webhooks​

View Webhooks​

Go to Account → Webhooks to see:

  • All configured webhooks
  • Status (enabled/disabled)
  • Event subscriptions
  • Recent deliveries

Edit Webhook​

  1. Click on the webhook
  2. Click Edit
  3. Modify settings
  4. Save changes

Changes take effect immediately.

Disable Webhook​

Temporarily stop deliveries:

  1. Click on the webhook
  2. Toggle Enabled off
  3. Events are not sent (or queued)

Re-enable anytime to resume.

Delete Webhook​

Permanently remove:

  1. Click on the webhook
  2. Click Delete
  3. Confirm deletion

Cannot be undone.

Multiple Webhooks​

Different Endpoints​

Create separate webhooks for:

  • Development vs. production
  • Different services
  • Different event types

Same Events, Multiple Webhooks​

Events can trigger multiple webhooks:

  • Each receives the same payload
  • Delivered independently
  • Failures don't affect others

Webhook Limits​

Per Plan​

PlanMax Webhooks
Pro5
EnterpriseUnlimited

Rate Limits​

  • Max 1000 deliveries per minute per webhook
  • Events queued if exceeded
  • Delivered when capacity available

Troubleshooting​

Webhook Not Receiving Events​

  1. Verify URL is correct and accessible
  2. Check webhook is enabled
  3. Verify subscribed to correct events
  4. Check your server logs for errors
  5. Test with Send Test feature

Events Delayed​

  • Check your endpoint response time
  • Ensure responding with 2xx quickly
  • High latency triggers retries

Duplicate Events​

  • Same event may be delivered multiple times
  • Use event ID for deduplication
  • This is by design for reliability

Next Steps​