Receive Real-Time Events with Moonshadow Webhooks

Configure Moonshadow webhooks to receive real-time event payloads to your server when integrations fire events or automations complete.

Moonshadow webhooks let you receive real-time HTTP callbacks to your server whenever events occur in your workspace. Instead of polling the API for changes, your application gets notified immediately when integrations fire events, automations complete, or other actions trigger.

What Are Webhooks

A webhook is an HTTP POST request that Moonshadow sends to a URL you control. When a subscribed event occurs, Moonshadow packages the event data as JSON and delivers it to your endpoint. This is more efficient than polling because your server only receives data when something actually happens.

Register a Webhook Endpoint

Create a webhook endpoint through the Moonshadow API. You need to provide a target URL and a list of event types to subscribe to.

curl -X POST https://api.moonshadow.dev/v1/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/moonshadow",
    "events": ["event.created", "automation.completed", "integration.connected"],
    "workspace_id": "ws_1234567890abcdef",
    "secret": "whsec_your_webhook_secret"
  }'

Response:

{
  "id": "whk_9876543210fedcba",
  "url": "https://your-app.com/webhooks/moonshadow",
  "events": ["event.created", "automation.completed", "integration.connected"],
  "workspace_id": "ws_1234567890abcdef",
  "status": "active",
  "created_at": "2024-01-15T10:30:00Z"
}

url · string · required

The HTTPS endpoint where Moonshadow sends event payloads.

events · array · required

List of event types to subscribe to. Use ["*"] to receive all events.

workspace_id · string · required

The workspace that owns this webhook.

secret · string · required

A secret string used to sign webhook payloads for verification.

Webhook Payload Shape

Every webhook payload has a consistent envelope. The data field contains the event-specific details.

{
  "id": "evt_abc123def456",
  "type": "event.created",
  "created_at": "2024-01-15T10:30:00Z",
  "workspace_id": "ws_1234567890abcdef",
  "data": {
    "integration_id": "int_abc123",
    "integration_type": "slack",
    "event_source": "slack.message.posted",
    "payload": {
      "channel": "#general",
      "user": "U1234567890",
      "text": "Hello from Slack!"
    }
  }
}

id · string

Unique identifier for this event delivery.

type · string

The event type that triggered this webhook.

created_at · string

ISO 8601 timestamp of when the event occurred.

data · object

Event-specific data, including the source integration and original payload.

Verify the Signature

Moonshadow signs every webhook payload with HMAC-SHA256 using the secret you provided during registration. Verify the signature to ensure requests come from Moonshadow and have not been tampered with.

The signature is sent in the X-Moonshadow-Signature header as a hex string.

Node.js

const crypto = require('crypto');

function verifyWebhook(body, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(body, 'utf8')
    .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(signature, 'hex'),
    Buffer.from(expected, 'hex')
  );
}

app.post('/webhooks/moonshadow', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-moonshadow-signature'];
  const secret = process.env.MOONSHADOW_WEBHOOK_SECRET;
  
  if (!verifyWebhook(req.body, signature, secret)) {
    return res.status(401).send('Invalid signature');
  }
  
  const event = JSON.parse(req.body);
  console.log('Received event:', event.type);
  
  res.status(200).send('OK');
});

Always verify the signature before processing the payload. Never trust unverified webhook requests.

Retries and Failure Handling

Moonshadow expects your endpoint to respond with a 2xx HTTP status code within 30 seconds. If your endpoint fails or times out, Moonshadow retries the delivery with exponential backoff.

Attempt	Delay After Previous Attempt
1	Immediate
2	5 seconds
3	25 seconds
4	2 minutes
5	10 minutes

After 5 failed attempts, Moonshadow marks the delivery as failed and stops retrying. You can view failed deliveries in the Events dashboard and manually retry them if needed.

Your webhook endpoint should return a 2xx response immediately after receiving the payload. Do any heavy processing asynchronously to avoid timeouts.

Respond with 200 OK as soon as you validate the signature and queue the event for processing. Handle the business logic in a background worker.

Full Webhook Handler Example

Here is a complete example that receives webhooks, verifies the signature, and handles different event types:

Node.js

const express = require('express');
const crypto = require('crypto');

const app = express();
const WEBHOOK_SECRET = process.env.MOONSHADOW_WEBHOOK_SECRET;

// Use raw body for signature verification
app.use('/webhooks/moonshadow', express.raw({ type: 'application/json' }));

function verifySignature(body, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(body, 'utf8')
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature, 'hex'),
    Buffer.from(expected, 'hex')
  );
}

app.post('/webhooks/moonshadow', (req, res) => {
  const signature = req.headers['x-moonshadow-signature'];
  
  if (!signature || !verifySignature(req.body, signature, WEBHOOK_SECRET)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }
  
  const event = JSON.parse(req.body);
  
  switch (event.type) {
    case 'event.created':
      console.log('New event:', event.data.payload);
      break;
    case 'automation.completed':
      console.log('Automation finished:', event.data.automation_id);
      break;
    case 'integration.connected':
      console.log('Integration added:', event.data.integration_type);
      break;
    default:
      console.log('Unhandled event:', event.type);
  }
  
  res.status(200).send('OK');
});

app.listen(3000, () => console.log('Webhook server running on port 3000'));

Next Steps

• Configure Notifications

  Route events to Slack, email, or other channels with notification rules

• API Rate Limits

  Understand request limits and how to handle rate limiting