Help Center / api

Setting up webhooks

Setting Up Webhooks

Webhooks notify your application when events happen in your account. Receive real-time updates without polling.

How Webhooks Work

1. Event occurs (e.g., domain registered)
2. We send HTTP POST to your endpoint
3. Your server processes the event
4. Responds with 200 OK

Creating a Webhook

1. Go to Settings > Webhooks
2. Click Add Endpoint
3. Enter your URL (must be HTTPS)
4. Select events to receive
5. Save

Webhook Events

Domain Events

VPS Events

Billing Events

Webhook Payload

{
  "id": "evt_1234567890",
  "type": "domain.registered",
  "created": 1640000000,
  "data": {
    "domain": "example.com",
    "registrant": "user@email.com",
    "expiration": "2025-01-01"
  }
}

Verifying Webhooks

Verify requests are from us using signatures:

const crypto = require('crypto')

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex')

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  )
}

// In your endpoint
app.post('/webhook', (req, res) => {
  const signature = req.headers['x-osir-signature']
  const isValid = verifyWebhook(req.rawBody, signature, webhookSecret)

  if (!isValid) {
    return res.status(401).send('Invalid signature')
  }

  // Process event
  res.status(200).send('OK')
})

Retry Policy

If your endpoint fails, we retry:

After 5 failures, the webhook is disabled.

Testing Webhooks

1. Go to your webhook settings
2. Click Send Test Event
3. Select event type
4. View the request/response

Webhook Logs

View delivery history:

1. Go to Webhooks > Select endpoint
2. Click Logs
3. See all attempts and responses
4. Replay failed events

Best Practices

• Respond quickly - Return 200 within 30 seconds
• Process async - Queue events for background processing
• Verify signatures - Always validate requests
• Handle duplicates - Events may be sent more than once
• Log everything - Keep records for debugging