Webhooks API

Manage real-time event subscriptions and receive webhook notifications

POST

/webhooks/create

Create a new webhook subscription to receive real-time events

Request

POST /api/v1/webhooks/create
X-API-Key: sk_live_your_key

{
  "url": "https://example.com/webhooks/auctions",
  "events": ["auction.bid", "auction.settled", "auction.created"]
}

Parameters

url

string, required

HTTPS endpoint where webhook events will be delivered. Must be a valid URL.

events

array of strings, required

Event types to subscribe to. Valid values: auction.created, auction.bid, auction.settled, auction.cancelled, etc

Response

{
  "success": true,
  "data": {
    "subscriptionId": "whk_abc123def456",
    "url": "https://example.com/webhooks/auctions",
    "events": ["auction.bid", "auction.settled", "auction.created"],
    "createdAt": 1234567890
  },
  "timestamp": 1234567890
}

GET

/webhooks

List all webhook subscriptions for your API key

Request

GET /api/v1/webhooks
X-API-Key: sk_live_your_key

Response

{
  "success": true,
  "data": {
    "webhooks": [
      {
        "id": "whk_abc123def456",
        "url": "https://example.com/webhooks/auctions",
        "events": ["auction.bid", "auction.settled"],
        "active": true,
        "createdAt": 1234567890,
        "lastDelivery": 1234567800
      }
    ],
    "total": 1
  },
  "timestamp": 1234567890
}

GET

/webhooks/:id

Get details of a specific webhook subscription

Request

GET /api/v1/webhooks/whk_abc123def456
X-API-Key: sk_live_your_key

Response

{
  "success": true,
  "data": {
    "id": "whk_abc123def456",
    "url": "https://example.com/webhooks/auctions",
    "events": ["auction.bid", "auction.settled", "auction.created"],
    "active": true,
    "createdAt": 1234567890
  },
  "timestamp": 1234567890
}

PUT

/webhooks/:id

Update an existing webhook subscription

Request

PUT /api/v1/webhooks/whk_abc123def456
X-API-Key: sk_live_your_key

{
  "url": "https://example.com/webhooks/auctions-updated",
  "events": ["auction.bid", "auction.settled"],
  "active": true
}

Parameters (all optional)

url

New webhook endpoint URL

events

New list of event types to subscribe to

active

Enable or disable the webhook (true/false)

DELETE

/webhooks/:id

Delete a webhook subscription

Request

DELETE /api/v1/webhooks/whk_abc123def456
X-API-Key: sk_live_your_key

Response

{
  "success": true,
  "data": {
    "success": true,
    "deletedId": "whk_abc123def456"
  },
  "timestamp": 1234567890
}

Subscribable Event Types

auction.created

Fired when a new auction is created

auction.bid

Fired when a bid is placed on an auction

auction.bid.extended

Fired when snipe protection extends the auction end time

auction.settled

Fired when an auction settles with a winning bid

auction.settled_unsold

Fired when an auction settles without meeting the reserve

auction.cancelled

Fired when an auction is cancelled by the seller

Webhook Payload Format

Each webhook delivery includes these headers and body:

Headers:
X-Webhook-Signature: <HMAC-SHA256 signature>
X-Webhook-ID: <unique event id>
X-Webhook-Event: <event type>
X-Webhook-Timestamp: <unix timestamp>

Body:
{
  "event": "auction.bid",
  "auctionId": "auction_123",
  "domain": "example.sol",
  "data": {
    "bidder": "7B4X5wUohEzB8UZjfAvaxS1huNY6q5p5XqvCH7r6T1Hj",
    "bidAmount": 2.5
  },
  "timestamp": 1234567890,
  "id": "evt_abc123"
}

Authentication

All webhook management endpoints require API key authentication. Include your API key in the X-API-Key header:

curl -X POST https://api.snsauctions.xyz/api/v1/webhooks/create \
  -H "X-API-Key: sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/webhooks", "events": ["auction.bid"]}'

Rate Limits

Management Endpoints

60 requests/minute (create, update, delete) | 100 requests/minute (list, get)

Webhook Delivery

Unlimited. Your endpoint should handle retries with exponential backoff.

Analytics

Creating Auctions

Follow Notify Join Discord