8004scan-webhooks

8004scan Webhooks — Real-Time Event Skill

Subscribe to real-time events from the 8004scan platform. Receive HTTP callbacks when agents are registered, feedback is submitted, validations complete, or stars are given.

Reference Map

File	When to read
{baseDir}/references/webhook-api.md	Webhook CRUD endpoints, request/response schemas
{baseDir}/references/events.md	All event types, payload schemas, trigger conditions
{baseDir}/references/verification.md	HMAC-SHA256 signature verification, security best practices

---

Base URL

https://www.8004scan.io/api/v1

Note: Webhook endpoints require authentication. Include X-API-Key header.

Authentication

All webhook management endpoints require a valid API key:

-H "X-API-Key: $EIGHTSCAN_API_KEY"

---

Request Classification

1. Register webhook ("set up a webhook", "notify me when...") → Register Webhook endpoint.
2. List webhooks ("show my webhooks", "what webhooks do I have?") → List Webhooks endpoint.
3. Update webhook ("change webhook URL", "add events to webhook") → Update Webhook endpoint.
4. Delete webhook ("remove webhook", "stop notifications") → Delete Webhook endpoint.
5. Check deliveries ("webhook delivery history", "failed deliveries") → Deliveries endpoint.
6. Verify signature ("how to verify webhook?", "HMAC validation") → Read references/verification.md.

---

Event Types

Event	Trigger
validation.requested	A validation request is submitted for an agent
validation.completed	A validator submits their attestation response
feedback.received	New feedback is submitted for an agent
feedback.revoked	Existing feedback is revoked by its submitter
star.received	An agent receives a star rating
star.removed	A star rating is removed

---

Quick Reference

Register a Webhook

curl -s -X POST "https://www.8004scan.io/api/v1/webhooks" \
  -H "X-API-Key: $EIGHTSCAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourserver.com/webhook",
    "events": ["feedback.received", "validation.completed"],
    "secret": "your-webhook-secret"
  }' | jq .

List Webhooks

curl -s "https://www.8004scan.io/api/v1/webhooks" \
  -H "X-API-Key: $EIGHTSCAN_API_KEY" | jq .

Update a Webhook

curl -s -X PATCH "https://www.8004scan.io/api/v1/webhooks/{webhookId}" \
  -H "X-API-Key: $EIGHTSCAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "events": ["feedback.received", "feedback.revoked", "star.received"],
    "active": true
  }' | jq .

Delete a Webhook

curl -s -X DELETE "https://www.8004scan.io/api/v1/webhooks/{webhookId}" \
  -H "X-API-Key: $EIGHTSCAN_API_KEY" | jq .

Check Delivery History

curl -s "https://www.8004scan.io/api/v1/webhooks/{webhookId}/deliveries?limit=10" \
  -H "X-API-Key: $EIGHTSCAN_API_KEY" | jq .

---

Webhook Payload Format

All webhook deliveries include:

{
  "event": "feedback.received",
  "timestamp": "2026-03-16T12:00:00Z",
  "data": {
    "chainId": 8453,
    "tokenId": 17,
    "agentId": "8453:17",
    ...event-specific fields...
  }
}

Headers on delivery:

• X-Webhook-Signature: HMAC-SHA256 hex digest
• X-Webhook-Event: Event type
• X-Webhook-Delivery-Id: Unique delivery ID
• Content-Type: application/json

---

Signature Verification

Verify every incoming webhook to ensure authenticity:

# The signature is: HMAC-SHA256(secret, request_body)
EXPECTED=$(echo -n "$BODY" | openssl dgst -sha256 -hmac "$WEBHOOK_SECRET" | awk '{print $2}')
if [ "$EXPECTED" = "$RECEIVED_SIGNATURE" ]; then
  echo "Valid"
fi

---

Retry Behavior

Failed deliveries (non-2xx response or timeout) are retried with exponential backoff:

Attempt	Delay
1	Immediate
2	1 minute
3	5 minutes
4	30 minutes
5	2 hours

After 5 failed attempts, the delivery is marked as permanently failed. Webhooks with repeated failures may be automatically disabled.

---

Examples

Example 1: Set up feedback notifications User: "Notify me when my agent gets feedback"

curl -s -X POST "https://www.8004scan.io/api/v1/webhooks" \
  -H "X-API-Key: $EIGHTSCAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://myserver.com/hook","events":["feedback.received","feedback.revoked"],"secret":"mysecret"}' | jq .

Example 2: Monitor validation progress User: "Alert me when validation completes"

curl -s -X POST "https://www.8004scan.io/api/v1/webhooks" \
  -H "X-API-Key: $EIGHTSCAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://myserver.com/hook","events":["validation.requested","validation.completed"],"secret":"mysecret"}' | jq .

Example 3: Debug failed deliveries User: "Why aren't my webhooks working?"

curl -s "https://www.8004scan.io/api/v1/webhooks/{id}/deliveries?limit=5" \
  -H "X-API-Key: $EIGHTSCAN_API_KEY" | jq '.data[] | {status, responseCode, attempt, createdAt}'