Skip to main content

Webhooks

Receive real-time HTTP notifications when events occur in your moncreneau account.

Introduction​

Webhooks allow you to receive automatic HTTP POST notifications when events occur, such as the creation or cancellation of an appointment. Instead of regular API polling, webhooks send data directly to your server.

Use Cases​

  • User Notifications: Send SMS/email when an appointment is validated
  • Synchronization: Update your local database in real-time
  • Analytics: Collect metrics on appointments
  • Integrations: Connect moncreneau to other systems (CRM, ERP, etc.)

Configuration​

1. Create a webhook endpoint​

Create an HTTPS endpoint on your server that accepts POST requests:

// Express.js
app.post('/webhooks/moncreneau', (req, res) => {
  const event = req.body;
  
  // Verify signature (see Security section)
  if (!verifySignature(req)) {
    return res.status(401).send('Invalid signature');
  }
  
  // Process event
  handleEvent(event);
  
  // Respond quickly
  res.status(200).send('OK');
});

2. Register the webhook​

Important: Webhooks must be configured from the web interface by a user with STAFF role (ADMIN or OWNER).

From the moncreneau dashboard:

  1. Settings → Webhooks
  2. Click New webhook
  3. Enter your URL: https://your-domain.com/webhooks/moncreneau
  4. Select events to receive
  5. Copy the generated secret (to verify signatures)
Web interface only

Webhook creation and management is exclusively done from the web interface. API keys cannot manage webhooks.

Event Format​

Each webhook contains:

{
  "id": "evt_abc123",
  "type": "appointment.created",
  "created": "2026-01-21T14:30:00Z",
  "data": {
    "object": {
      "id": 12345,
      "departmentId": 5,
      "dateTime": "2026-01-25T14:30:00",
      "status": "SCHEDULED",
      "name": "Jean Dupont",
      "phone": "+224621234567",
      "qrCode": "https://moncreneau.gn/qr/12345"
    }
  }
}

HTTP Headers​

Each webhook request includes these headers:

POST /webhooks/moncreneau HTTP/1.1
Host: your-domain.com
Content-Type: application/json
X-Moncreneau-Event: appointment.created
X-Moncreneau-Signature: sha256=5d41402abc4b2a76b9719d911017c592
X-Moncreneau-Delivery: 550e8400-e29b-41d4-a716-446655440000
User-Agent: Moncreneau-Webhooks/1.0
  • X-Moncreneau-Event: Event type
  • X-Moncreneau-Signature: HMAC-SHA256 signature of payload
  • X-Moncreneau-Delivery: Unique delivery ID

Expected Response​

Your endpoint must:

  • Respond with a 2xx code (200, 201, 204) in less than 5 seconds
  • Process the event asynchronously if necessary
  • Be idempotent (same event = same result)
// ✅ Good: Quick response + async processing
app.post('/webhooks', async (req, res) => {
  const event = req.body;
  
  // Respond immediately
  res.status(200).send('OK');
  
  // Process in background
  processEventAsync(event);
});

// ❌ Bad: Long processing before response
app.post('/webhooks', async (req, res) => {
  const event = req.body;
  
  await sendEmail(event); // May take >5s
  await updateDatabase(event);
  
  res.status(200).send('OK'); // Too late!
});

Retry Logic​

If your endpoint doesn't respond with 2xx:

  • Attempt 1: Immediately
  • Attempt 2: After 1 minute
  • Attempt 3: After 5 minutes
  • Attempt 4: After 30 minutes
  • Attempt 5: After 2 hours
  • Abandon: After 24 hours

Debugging​

Webhook Logs​

Check logs in Dashboard → Webhooks → Logs:

  • Status of each delivery (success, failure)
  • Sent payload
  • Received response
  • Response time

Manual Replay​

You can replay a webhook from the logs for debugging.

Next Steps​

Last updated on