Webhooks

Available events

Register a webhook

POST /webhooks
{
  "url": "https://your-app.com/dark-obsidian-webhook",
  "events": ["sale.completed", "stock.low"],
  "secret": "optional-secret-for-signature-verification"
}

Webhook payload format

Dark Obsidian sends a JSON POST to your URL:

POST https://your-app.com/dark-obsidian-webhook
Content-Type: application/json
X-Dark-Obsidian-Event: sale.completed
X-Dark-Obsidian-Signature: your-secret  (if configured)

{
  "event": "sale.completed",
  "timestamp": "2026-06-02T14:30:00.000Z",
  "data": {
    "sale_id": "uuid",
    "sale_number": "S-0042",
    "total": 199.98,
    "customer_id": "uuid",
    "items": [...]
  }
}

Receiving webhooks (Node.js example)

const express = require('express')
const app = express()
app.use(express.json())

app.post('/dark-obsidian-webhook', (req, res) => {
  const event = req.headers['x-dark-obsidian-event']
  const payload = req.body

  switch (event) {
    case 'sale.completed':
      console.log(`New order: ${payload.data.sale_number}`)
      // Sync to your system
      break

    case 'stock.low':
      console.log(`Low stock alert: ${payload.data.product_id}`)
      // Send reorder alert
      break
  }

  res.status(200).json({ received: true })
})

app.listen(3000)

Manage webhooks via API

# List webhooks
GET /webhooks

# Update webhook
PUT /webhooks/:id
{ "is_active": false }

# Delete webhook
DELETE /webhooks/:id

Retry policy

Dark Obsidian makes a best-effort delivery. Failed deliveries are not automatically retried - use idempotent handlers and consider polling the API as a backup for critical integrations.