Webhooks

Webhooks enable real-time event-driven integration between M3 Forge apps and external systems. Push notifications when important events occur, trigger downstream processes, and keep external systems synchronized.

What Are Webhooks?

Webhooks are HTTP callbacks triggered by events:

1. Event occurs in M3 Forge (workflow completes, document processed, etc.)
2. M3 Forge sends HTTP POST to configured URL
3. Your endpoint receives event payload
4. Your system processes event and responds

Unlike polling, webhooks provide instant notifications with minimal overhead.

Common Use Cases

Workflow Integration:

• Notify Slack when workflow completes
• Update CRM when document approved
• Trigger downstream automation

External System Sync:

• Sync extracted data to database
• Update ERP with invoice details
• Push documents to document management system

Monitoring and Alerts:

• Alert on workflow failures
• Notify on SLA breaches
• Track processing metrics

Custom Automation:

• Chain multiple systems together
• Build event-driven architectures
• Implement custom business logic

Creating Webhooks

Webhook Payloads

All webhook payloads share common structure:

{
  "id": "evt_1234567890",
  "event": "workflow.completed",
  "timestamp": "2024-03-19T10:30:00Z",
  "version": "1.0",
  "data": {
    // Event-specific data
  }
}

Common Fields

Event-Specific Payloads

{
  "id": "evt_abc123",
  "event": "workflow.completed",
  "timestamp": "2024-03-19T10:30:00Z",
  "data": {
    "workflowId": "wf-123",
    "executionId": "exec-456",
    "status": "completed",
    "duration": 12500,
    "inputs": { ... },
    "outputs": { ... }
  }
}

{
  "id": "evt_def456",
  "event": "document.processed",
  "timestamp": "2024-03-19T10:30:00Z",
  "data": {
    "documentId": "doc-789",
    "filename": "invoice.pdf",
    "classification": {
      "type": "invoice",
      "confidence": 0.95
    },
    "extraction": {
      "invoice_number": "INV-001",
      "total": 1250.00,
      "date": "2024-03-15"
    }
  }
}

{
  "id": "evt_ghi789",
  "event": "hitl.request.completed",
  "timestamp": "2024-03-19T10:30:00Z",
  "data": {
    "requestId": "req-123",
    "type": "approval",
    "decision": "approved",
    "reviewer": "user-456",
    "notes": "Approved - looks good",
    "completedAt": "2024-03-19T10:25:00Z"
  }
}

{
  "id": "evt_jkl012",
  "event": "submission.closed",
  "timestamp": "2024-03-19T10:30:00Z",
  "data": {
    "submissionId": "sub-123",
    "tenantId": "tenant-456",
    "documentCount": 25,
    "reviewedCount": 25,
    "approvedCount": 23,
    "rejectedCount": 2
  }
}

Implementing Webhook Endpoints

Create endpoint to receive webhooks:

const express = require('express');
const crypto = require('crypto');
 
const app = express();
app.use(express.json());
 
const WEBHOOK_SECRET = process.env.WEBHOOK_SECRET;
 
app.post('/webhooks/m3studio', (req, res) => {
  // Verify signature
  const signature = req.headers['x-m3-signature'];
  const payload = JSON.stringify(req.body);
  const expected = crypto
    .createHmac('sha256', WEBHOOK_SECRET)
    .update(payload)
    .digest('hex');
 
  if (signature !== expected) {
    return res.status(401).json({ error: 'Invalid signature' });
  }
 
  // Process event
  const { event, data } = req.body;
 
  switch (event) {
    case 'workflow.completed':
      handleWorkflowComplete(data);
      break;
    case 'document.processed':
      handleDocumentProcessed(data);
      break;
    default:
      console.log(`Unhandled event: ${event}`);
  }
 
  // Respond quickly (process async)
  res.status(200).json({ received: true });
});
 
app.listen(3000);

from flask import Flask, request, jsonify
import hmac
import hashlib
import os
 
app = Flask(__name__)
WEBHOOK_SECRET = os.environ['WEBHOOK_SECRET']
 
@app.route('/webhooks/m3studio', methods=['POST'])
def webhook():
    # Verify signature
    signature = request.headers.get('X-M3-Signature')
    payload = request.get_data()
    expected = hmac.new(
        WEBHOOK_SECRET.encode(),
        payload,
        hashlib.sha256
    ).hexdigest()
 
    if signature != expected:
        return jsonify({'error': 'Invalid signature'}), 401
 
    # Process event
    event_data = request.json
    event = event_data['event']
    data = event_data['data']
 
    if event == 'workflow.completed':
        handle_workflow_complete(data)
    elif event == 'document.processed':
        handle_document_processed(data)
 
    return jsonify({'received': True}), 200
 
if __name__ == '__main__':
    app.run(port=3000)

package main
 
import (
    "crypto/hmac"
    "crypto/sha256"
    "encoding/hex"
    "encoding/json"
    "net/http"
    "os"
)
 
type WebhookPayload struct {
    ID        string                 `json:"id"`
    Event     string                 `json:"event"`
    Timestamp string                 `json:"timestamp"`
    Data      map[string]interface{} `json:"data"`
}
 
func webhookHandler(w http.ResponseWriter, r *http.Request) {
    // Verify signature
    signature := r.Header.Get("X-M3-Signature")
    body, _ := io.ReadAll(r.Body)
 
    mac := hmac.New(sha256.New, []byte(os.Getenv("WEBHOOK_SECRET")))
    mac.Write(body)
    expected := hex.EncodeToString(mac.Sum(nil))
 
    if signature != expected {
        http.Error(w, "Invalid signature", http.StatusUnauthorized)
        return
    }
 
    // Process event
    var payload WebhookPayload
    json.Unmarshal(body, &payload)
 
    switch payload.Event {
    case "workflow.completed":
        handleWorkflowComplete(payload.Data)
    case "document.processed":
        handleDocumentProcessed(payload.Data)
    }
 
    json.NewEncoder(w).Encode(map[string]bool{"received": true})
}
 
func main() {
    http.HandleFunc("/webhooks/m3studio", webhookHandler)
    http.ListenAndServe(":3000", nil)
}

Security Verification

Always verify webhook signatures:

Signature Header:

• M3 Forge sends signature in X-M3-Signature header
• HMAC-SHA256 of payload using webhook secret
• Compare with computed signature

Signature Calculation:

signature = HMAC-SHA256(secret, payload)

Reject requests with invalid signatures.

Handling Failures

Webhook deliveries can fail. Implement robust error handling:

Retry Logic

M3 Forge automatically retries failed webhooks:

1. Initial delivery attempt
2. Wait 1 second, retry
3. Wait 2 seconds, retry
4. Wait 4 seconds, retry
5. Wait 8 seconds, final retry
6. Mark as failed after max retries

Idempotency

Process events idempotently to handle duplicate deliveries:

const processedEvents = new Set();
 
function handleEvent(eventId, data) {
  // Check if already processed
  if (processedEvents.has(eventId)) {
    console.log('Duplicate event, skipping');
    return;
  }
 
  // Process event
  processData(data);
 
  // Mark as processed
  processedEvents.add(eventId);
}

Use database or cache for persistent deduplication.

Error Responses

Respond appropriately to indicate success/failure:

Success:

• Status code: 200 or 204
• M3 Forge marks delivery successful

Transient Error (retry):

• Status code: 500, 502, 503, 504
• M3 Forge retries delivery

Permanent Error (don’t retry):

• Status code: 400, 401, 403, 404
• M3 Forge does not retry

Timeout:

• No response within timeout (5 seconds)
• M3 Forge retries

Respond quickly (< 5 seconds) even if processing takes longer. Queue event for async processing.

Monitoring Webhooks

Track webhook health and deliveries:

Webhook Logs

View delivery logs in M3 Forge:

1. Navigate to webhook settings
2. Click Delivery Logs
3. View recent deliveries:
   • Timestamp
   • Event type
   • Status (success, failed, retrying)
   • Response code and time
   • Payload (click to view)

Filter logs by:

• Date range
• Event type
• Status
• Response code

Alerts

Configure alerts for webhook failures:

• Failed deliveries — Alert after N consecutive failures
• High latency — Alert if response time exceeds threshold
• Disabled webhooks — Alert if webhook auto-disabled due to failures

Set alert destinations (email, Slack, PagerDuty).

Metrics

Monitor webhook performance:

• Delivery rate — Webhooks sent per minute
• Success rate — Percentage of successful deliveries
• Latency — Average response time
• Retry rate — Percentage requiring retries

Access metrics in Admin → Webhooks → Metrics.

Advanced Features

Webhook Filters

Filter which events trigger webhook:

Conditional Triggers:

• Only trigger for specific workflow IDs
• Filter by document type
• Limit to specific tenants
• Custom filter expressions

Example Filter:

{
  "event": "workflow.completed",
  "filter": {
    "data.workflowId": { "$in": ["wf-123", "wf-456"] },
    "data.status": "completed"
  }
}

Reduces noise by sending only relevant events.

Webhook Transformations

Transform payloads before delivery:

Template:

{
  "customField": "{{ event }}",
  "details": {
    "id": "{{ data.workflowId }}",
    "result": "{{ data.outputs.result }}"
  }
}

Maps M3 Forge payload to external system’s expected format.

Batch Webhooks

Send multiple events in single request:

Settings:

• Batch size — Max events per request (default: 1, max: 100)
• Batch window — Max time to accumulate events (default: 0, max: 60s)

Batched Payload:

{
  "batch": true,
  "events": [
    { "id": "evt_1", "event": "...", "data": { ... } },
    { "id": "evt_2", "event": "...", "data": { ... } }
  ]
}

Reduces HTTP overhead for high-volume events.

Webhook Proxies

Route webhooks through proxy for additional processing:

Use Cases:

• Add authentication
• Transform payloads
• Fan out to multiple endpoints
• Rate limiting

Configure proxy URL in webhook settings.

Debugging Webhooks

Troubleshoot webhook issues:

Local Testing

Test webhooks locally during development:

Tools:

• ngrok  — Expose localhost to internet
• webhook.site  — Inspect webhook payloads
• requestbin  — Debug webhook requests

Workflow:

# Expose local server
ngrok http 3000
 
# Use ngrok URL in webhook settings
https://abc123.ngrok.io/webhooks/m3studio

Delivery Testing

Test webhook delivery without triggering real event:

1. Navigate to webhook settings
2. Click Send Test Event
3. Select event type
4. Optionally customize payload
5. Click Send

Review response and logs.

Payload Inspection

Examine webhook payloads:

1. View delivery logs
2. Click failed delivery
3. See request/response details:
   • Full payload
   • Request headers
   • Response status and body
   • Error message (if any)

Use to debug payload format issues.

Best Practices

Endpoint Design

• Respond quickly — Acknowledge receipt within 5 seconds
• Process async — Queue events for background processing
• Return correct status — Use appropriate HTTP codes
• Log everything — Retain logs for debugging

Security

• Verify signatures — Always validate X-M3-Signature
• Use HTTPS — Encrypt webhook traffic
• Whitelist IPs — Restrict to M3 Forge IP ranges
• Rotate secrets — Periodically update signing secrets

Reliability

• Implement idempotency — Handle duplicate events safely
• Retry failures — Implement own retry logic for critical events
• Monitor alerts — Set up alerts for failures
• Have fallback — Don’t rely solely on webhooks for critical operations

Scalability

• Handle bursts — Queue events to handle spikes
• Load balance — Distribute across multiple endpoints
• Batch processing — Process events in batches for efficiency
• Rate limit — Protect your systems from overload

Next Steps

• Build apps with App Builder and Custom Apps
• Integrate with Workflows for end-to-end automation
• Use Chat Assistant for conversational interfaces
• Monitor webhook health in Admin