Webhooks API Reference
Create, manage, and monitor webhooks via the API.
Endpoints Overview
| Method | Endpoint | Description |
|---|---|---|
| GET | /v1/webhooks | List all webhooks |
| POST | /v1/webhooks | Create a webhook |
| GET | /v1/webhooks/{id} | Get webhook details |
| PUT | /v1/webhooks/{id} | Update a webhook |
| DELETE | /v1/webhooks/{id} | Delete a webhook |
| POST | /v1/webhooks/{id}/test | Test a webhook |
| GET | /v1/webhooks/{id}/deliveries | Get delivery history |
List Webhooks
Retrieve all webhooks for your account.
Request
GET /v1/webhooks
Query Parameters
| Parameter | Type | Description |
|---|---|---|
limit | integer | Items per page (max 100) |
offset | integer | Skip items |
enabled | boolean | Filter by status |
Example
curl https://api.tagd-ai.com/v1/webhooks \
-H "Authorization: Bearer YOUR_API_KEY"
Response
{
"success": true,
"data": [
{
"id": "wh_abc123",
"name": "Tag Updates",
"url": "https://example.com/webhook",
"events": ["tag.created", "tag.updated"],
"enabled": true,
"created_at": "2024-01-15T10:30:00Z"
}
],
"pagination": {
"total": 1,
"limit": 20,
"offset": 0,
"has_more": false
}
}
Create Webhook
Create a new webhook.
Request
POST /v1/webhooks
Content-Type: application/json
Body Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Webhook name |
url | string | Yes | Endpoint URL (HTTPS required) |
events | array | Yes | Events to subscribe to |
secret | string | No | Signing secret |
headers | object | No | Custom headers |
enabled | boolean | No | Active status (default: true) |
Available Events
| Event | Description |
|---|---|
tag.created | New tag created |
tag.updated | Tag content changed |
tag.deleted | Tag deleted |
tag.viewed | Tag was accessed |
file.uploaded | File added to tag |
file.deleted | File removed |
qr.generated | QR code generated |
qr.scanned | QR code scanned |
Example
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", "tag.deleted"],
"secret": "your-webhook-secret",
"headers": {
"X-Custom-Header": "custom-value"
}
}'
Response
{
"success": true,
"data": {
"id": "wh_xyz789",
"name": "Production Webhook",
"url": "https://api.example.com/tagd-webhook",
"events": ["tag.created", "tag.updated", "tag.deleted"],
"enabled": true,
"secret": "your-webhook-secret",
"created_at": "2024-01-15T10:30:00Z"
}
}
Get Webhook
Retrieve webhook details.
Request
GET /v1/webhooks/{id}
Example
curl https://api.tagd-ai.com/v1/webhooks/wh_xyz789 \
-H "Authorization: Bearer YOUR_API_KEY"
Response
{
"success": true,
"data": {
"id": "wh_xyz789",
"name": "Production Webhook",
"url": "https://api.example.com/tagd-webhook",
"events": ["tag.created", "tag.updated", "tag.deleted"],
"enabled": true,
"secret": "your-webhook-secret",
"headers": {
"X-Custom-Header": "custom-value"
},
"stats": {
"total_deliveries": 150,
"successful": 148,
"failed": 2,
"last_delivery_at": "2024-01-15T14:30:00Z"
},
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-15T12:00:00Z"
}
}
Update Webhook
Update webhook configuration.
Request
PUT /v1/webhooks/{id}
Content-Type: application/json
Body Parameters
All parameters optional:
| Parameter | Type | Description |
|---|---|---|
name | string | Webhook name |
url | string | Endpoint URL |
events | array | Events to subscribe to |
secret | string | Signing secret |
headers | object | Custom headers |
enabled | boolean | Active status |
Example
curl -X PUT https://api.tagd-ai.com/v1/webhooks/wh_xyz789 \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"enabled": false
}'
Delete Webhook
Remove a webhook.
Request
DELETE /v1/webhooks/{id}
Example
curl -X DELETE https://api.tagd-ai.com/v1/webhooks/wh_xyz789 \
-H "Authorization: Bearer YOUR_API_KEY"
Response
{
"success": true,
"message": "Webhook deleted successfully"
}
Test Webhook
Send a test event to the webhook.
Request
POST /v1/webhooks/{id}/test
Content-Type: application/json
Body Parameters
| Parameter | Type | Description |
|---|---|---|
event | string | Event type to simulate |
Example
curl -X POST https://api.tagd-ai.com/v1/webhooks/wh_xyz789/test \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"event": "tag.created"
}'
Response
{
"success": true,
"data": {
"delivery_id": "del_test123",
"status": "success",
"response_code": 200,
"response_time_ms": 245
}
}
Get Delivery History
View webhook delivery attempts.
Request
GET /v1/webhooks/{id}/deliveries
Query Parameters
| Parameter | Type | Description |
|---|---|---|
limit | integer | Items per page |
offset | integer | Skip items |
status | string | Filter: success, failed |
Example
curl https://api.tagd-ai.com/v1/webhooks/wh_xyz789/deliveries \
-H "Authorization: Bearer YOUR_API_KEY"
Response
{
"success": true,
"data": [
{
"id": "del_abc123",
"event": "tag.created",
"status": "success",
"response_code": 200,
"response_time_ms": 156,
"attempt": 1,
"delivered_at": "2024-01-15T14:30:00Z",
"payload": {
"event": "tag.created",
"data": {...}
}
}
],
"pagination": {
"total": 150,
"limit": 20,
"offset": 0,
"has_more": true
}
}
Retry Failed Delivery
Retry a failed webhook delivery.
Request
POST /v1/webhooks/{id}/deliveries/{delivery_id}/retry
Example
curl -X POST https://api.tagd-ai.com/v1/webhooks/wh_xyz789/deliveries/del_abc123/retry \
-H "Authorization: Bearer YOUR_API_KEY"
Webhook Limits
| Plan | Max Webhooks |
|---|---|
| Pro | 5 |
| Enterprise | Unlimited |
Error Responses
400 Bad Request
{
"success": false,
"error": {
"code": "invalid_url",
"message": "Webhook URL must use HTTPS"
}
}
402 Payment Required
{
"success": false,
"error": {
"code": "webhook_limit_reached",
"message": "Maximum webhooks reached for your plan"
}
}