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/$PROJECT-ID', {
  method: 'POST',
  headers: {
    'X-API-KEY': 'your-api-key',
    'Authorization': 'Bearer your-token',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    op: 'collection.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

Best Practices

• Security: Always verify signatures and use HTTPS
• Reliability: Return 2xx status codes quickly, handle duplicates with Webhook-Id
• Performance: Process webhooks asynchronously for heavy operations
• Testing: Use ngrok for local development

Error Handling

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