Setting Up Webhook Notifications

Integrate domain alerts directly into your application using webhooks. We support both GET and POST methods.

Step 1: Configure Your Webhook

1. Go to your Notifications Dashboard
2. Enter your webhook URL
3. Select either GET or POST method
4. Use the "Test" button to verify it's working
5. Click "Save"

Webhook Payload

For POST requests, you'll receive a JSON payload:

{
  "domain": "example.com",
  "price": 1000,
  "currency": "USD",
  "bids": 5,
  "expires_at_utc": "2024-03-20T15:04:05Z",
  "listing_url": "https://yournextdomain.com/d/example.com",
  "message": "The listing for example.com ends in about 2 hours. Bids: 5, Price: $1000..."
}

For GET requests, these fields are sent as URL query parameters.

Security: Verifying Webhooks

All webhook requests include a signature header X-Webhook-Signature. You should verify this signature to ensure the request came from us.

JavaScript example to verify the signature:

const crypto = require('crypto');

async function handleWebhook(req, res) {
  const signature = req.headers['x-webhook-signature'];
  const secret = process.env.WEBHOOK_SECRET; // Get secret from environment variable
  
  // For POST requests
  const payload = JSON.stringify(req.body);

  // For GET requests
  // const payload = req.url.split('?')[1];

  const hmac = crypto.createHmac('sha256', secret);
  hmac.update(payload);
  const calculatedSignature = hmac.digest('hex');

  if (signature !== calculatedSignature) {
    return res.status(401).send('Invalid signature');
  }

  // Process the webhook...
  res.status(200).send('OK');
}

Rotating Webhook Secrets

To get a new webhook secret:

1. Delete your existing webhook
2. Create a new webhook with the same URL
3. A new secret will be automatically generated

Troubleshooting

• Ensure your endpoint is publicly accessible
• Check that your endpoint responds within 30 seconds
• Verify your endpoint returns a 2xx status code
• For POST requests, ensure you can handle JSON content
• For GET requests, ensure your endpoint can handle long URLs