Webhooks & Integrations

SinglebaseCloud provides event-driven webhooks that notify your application when data changes occur. Webhooks follow the Standard Webhooks specification for consistent, secure delivery.

Supported Events

Service	Event	Description
Datastore	document.created	Fired when a new document is inserted
Datastore	document.updated	Fired when an existing document is modified
Datastore	document.deleted	Fired when a document is deleted
Auth	user.signedup	Fired when a new user registers
Auth	user.signedin	Fired when a user signs in (optional)
Auth	user.signedout	Fired when a user signs out (optional)

Setup

1. Go to Settings > Webhooks in the Console
2. Click Add Webhook
3. Configure endpoint URL, events, and secret key
4. Save configuration

Webhook Format

Headers

POST /webhook HTTP/1.1
Content-Type: application/json
Webhook-Id: msg_2Lh9TbZmKPTOlWTXsnEgWEYf2FQ
Webhook-Timestamp: 1681234567
Webhook-Signature: v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE=

Payload Structure

Datastore Events:

{
  "type": "document.created",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "_key": "user_xyz789",
    "collection": "users"
  }
}

Auth Events:

{
  "type": "user.signedup", 
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "_key": "user_new456"
  }
}

Fetching Full Data

Webhooks contain only the document key. Fetch complete data using the API:

// Webhook received
const webhook = {
  "type": "document.created",
  "data": { "_key": "user_xyz789", "collection": "users" }
};

// Fetch full document
const response = await fetch('https://cloud.singlebaseapis.com/api/$ENDPOINT_KEY', {
  method: 'POST',
  headers: {
    'X-API-KEY': 'your-api-key',
    'Authorization': 'Bearer your-token',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    op: 'db.find',
    collection: webhook.data.collection,
    match: { "_key": webhook.data._key }
  })
});

Signature Verification

Always verify webhook signatures:

import crypto from 'crypto';

function verifySignature(payload, secret, signature, timestamp) {
  const hmac = crypto.createHmac('sha256', secret);
  hmac.update(`${timestamp}.${payload}`);
  const expected = hmac.digest('base64');
  const received = signature.replace('v1,', '');
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(received));
}

Complete Example

import express from 'express';
import crypto from 'crypto';

const app = express();
app.use('/webhook', express.raw({type: 'application/json'}));

app.post('/webhook', async (req, res) => {
  const payload = req.body.toString();
  const signature = req.headers['webhook-signature'];
  const timestamp = req.headers['webhook-timestamp'];
  
  // Verify signature
  if (!verifySignature(payload, process.env.WEBHOOK_SECRET, signature, timestamp)) {
    return res.status(401).json({error: 'Invalid signature'});
  }
  
  const event = JSON.parse(payload);
  
  // Handle events
  switch (event.type) {
    case 'user.signedup':
      await handleNewUser(event.data._key);
      break;
    case 'document.created':
      await handleNewDocument(event.data._key, event.data.collection);
      break;
  }
  
  res.status(200).json({received: true});
});

async function handleNewUser(userKey) {
  // Fetch user data and send welcome email
  const userData = await fetchUserData(userKey);
  await sendWelcomeEmail(userData.email);
}

app.listen(3000);

Third-Party Integrations

Zapier

1. Use "Webhooks by Zapier" trigger
2. Copy webhook URL to SinglebaseCloud settings
3. Connect to 1000+ apps (Gmail, Slack, etc.)

n8n

1. Add Webhook node with your endpoint
2. Process events with workflow nodes
3. Connect to external services

Error Handling

SinglebaseCloud retries failed webhooks up to 5 times with exponential backoff. Implement idempotency using the Webhook-Id header to handle duplicates gracefully.