Webhooks

Webhooks allow you to receive real-time HTTP notifications when events occur in your Memokit account.

Overview

When you configure a webhook, Memokit will send HTTP POST requests to your specified URL whenever subscribed events occur. This enables real-time integrations without polling the API.

Webhook Events

Event	Description
`memory.created`	A new memory was created
`memory.updated`	A memory was updated
`memory.deleted`	A memory was deleted

Webhook Payload

All webhook payloads follow this structure:

{
  "id": "wh_delivery_abc123",
  "event": "memory.created",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "id": "mem_abc123",
    "content": "The user mentioned...",
    "userId": "user_123",
    "createdAt": "2024-01-15T10:30:00Z"
  }
}

Setting Up Webhooks

1. Create a Webhook Endpoint

First, create an endpoint on your server that can receive POST requests:

// Express.js example
app.post('/webhooks/memokit', (req, res) => {
  const signature = req.headers['x-memokit-signature'];
  const payload = req.body;

  // Verify signature
  if (!verifySignature(payload, signature, webhookSecret)) {
    return res.status(401).send('Invalid signature');
  }

  // Process the event
  switch (payload.event) {
    case 'memory.created':
      handleMemoryCreated(payload.data);
      break;
    case 'memory.updated':
      handleMemoryUpdated(payload.data);
      break;
    case 'memory.deleted':
      handleMemoryDeleted(payload.data);
      break;
  }

  res.status(200).send('OK');
});

2. Register the Webhook

In the Memokit Console:

Go to Webhooks in the sidebar
Click Create Webhook
Enter your endpoint URL
Select the events you want to receive
Save the webhook

3. Verify Signatures

Each webhook request includes a signature header for verification:

X-Memokit-Signature: sha256=abc123...

Verify the signature using HMAC-SHA256:

const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
  const expectedSignature = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

Webhook Retries

If your endpoint returns an error (non-2xx status code), Memokit will retry the delivery:

Attempt	Delay
1	Immediate
2	1 minute
3	5 minutes
4	30 minutes
5	2 hours

After 5 failed attempts, the webhook delivery is marked as failed.

Best Practices

Return Quickly

Return a 200 response as soon as possible. Process webhook data asynchronously:

app.post('/webhooks/memokit', async (req, res) => {
  // Verify signature
  if (!verifySignature(req.body, req.headers['x-memokit-signature'], secret)) {
    return res.status(401).send('Invalid signature');
  }

  // Queue for processing
  await queue.add('process-webhook', req.body);

  // Return immediately
  res.status(200).send('OK');
});

Handle Duplicates

Webhook deliveries may be sent more than once. Use the delivery ID to deduplicate:

async function processWebhook(payload) {
  const deliveryId = payload.id;

  // Check if already processed
  if (await isDeliveryProcessed(deliveryId)) {
    return;
  }

  // Process the webhook
  await handleWebhookEvent(payload);

  // Mark as processed
  await markDeliveryProcessed(deliveryId);
}

Use HTTPS

Always use HTTPS endpoints to ensure webhook data is encrypted in transit.

Viewing Webhook Logs

In the Memokit Console, you can view webhook delivery logs:

Go to Webhooks
Click on a webhook
View the Delivery Logs tab

Each log entry shows:

Delivery timestamp
Event type
Response status code
Response time
Request/response bodies (for debugging)

Error Codes

Code	Description
`WEBHOOK_NOT_FOUND`	The specified webhook does not exist
`INVALID_WEBHOOK_URL`	The webhook URL is not valid
`WEBHOOK_DELIVERY_FAILED`	The webhook delivery failed after all retries

Webhooks

On this page