Outbound Webhooks#

mutation {
  createWebhookSubscription(
    name: "Message Handler"
    targetUrl: "https://myapp.com/webhooks/outeract"
    eventPatterns: ["message.inbound", "message.outbound"]
    secret: "my-webhook-secret-32chars-minimum"
  ) {
    id
    name
    targetUrl
    eventPatterns
    status
  }
}

curl -X POST https://api.outeract.com/v1/webhook-subscriptions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Outeract-App-ID: app_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Message Handler",
    "target_url": "https://myapp.com/webhooks/outeract",
    "event_patterns": ["message.inbound", "message.outbound"],
    "secret": "my-webhook-secret-32chars-minimum"
  }'

["message.inbound", "message.outbound"]

["message.*"]

["*"]

{
  "id": "whd_abc123",
  "subscription_id": "ws_xyz789",
  "event_id": "evt_123456",
  "event_type": "message.inbound",
  "app_id": "app_abc123",
  "payload": {
    "message": {
      "text": "Hello!",
      "role": "user"
    },
    "platform": "whatsapp",
    "external_message_id": "wamid.xyz"
  },
  "edges": {
    "sent_by": {
      "platform_user_id": "pu_xyz789",
      "external_id": "+14155551234",
      "name": "John Doe"
    },
    "sent_to": {
      "platform_user_id": "pu_system",
      "external_id": "+14155550000",
      "is_system_user": true
    }
  },
  "created_at": "2024-01-15T10:30:00Z",
  "timestamp": "2024-01-15T10:30:01Z"
}

X-Outeract-Signature: sha256=abc123...
X-Outeract-Timestamp: 1705320600
X-Outeract-Delivery-ID: whd_abc123

import hmac
import hashlib
import time

def verify_webhook(
    body: bytes,
    signature: str,
    timestamp: str,
    secret: str,
    tolerance: int = 300  # 5 minutes
) -> bool:
    # Check timestamp to prevent replay attacks
    current_time = int(time.time())
    webhook_time = int(timestamp)
    if abs(current_time - webhook_time) > tolerance:
        return False

    # Construct signed payload
    signed_payload = f"{timestamp}.{body.decode()}"

    # Calculate expected signature
    expected = "sha256=" + hmac.new(
        secret.encode(),
        signed_payload.encode(),
        hashlib.sha256
    ).hexdigest()

    # Constant-time comparison
    return hmac.compare_digest(expected, signature)

const crypto = require('crypto');

function verifyWebhook(body, signature, timestamp, secret, tolerance = 300) {
    // Check timestamp
    const currentTime = Math.floor(Date.now() / 1000);
    const webhookTime = parseInt(timestamp);
    if (Math.abs(currentTime - webhookTime) > tolerance) {
        return false;
    }

    // Calculate expected signature
    const signedPayload = `${timestamp}.${body}`;
    const expected = 'sha256=' + crypto
        .createHmac('sha256', secret)
        .update(signedPayload)
        .digest('hex');

    // Constant-time comparison
    return crypto.timingSafeEqual(
        Buffer.from(expected),
        Buffer.from(signature)
    );
}

{
  "received": true
}

HTTP/1.1 200 OK

HTTP/1.1 500 Internal Server Error

{
  "error": "Processing failed"
}

X-Outeract-Retry-Count: 2
X-Outeract-Original-Timestamp: 1705320600

query {
  webhookSubscriptions {
    id
    name
    targetUrl
    eventPatterns
    status
    createdAt
  }
}

mutation {
  updateWebhookSubscription(
    id: "ws_abc123"
    name: "Updated Name"
    eventPatterns: ["message.*", "custom.*"]
  ) {
    id
    name
    eventPatterns
  }
}

mutation {
  updateWebhookSubscription(
    id: "ws_abc123"
    status: PAUSED
  ) {
    id
    status
  }
}

mutation {
  deleteWebhookSubscription(id: "ws_abc123")
}

query {
  webhookDeliveryLogs(
    webhookSubscriptionId: "ws_abc123"
    first: 20
  ) {
    edges {
      node {
        id
        eventId
        eventType
        status
        statusCode
        attemptCount
        duration
        errorMessage
        createdAt
      }
    }
  }
}

mutation {
  testWebhookSubscription(id: "ws_abc123") {
    success
    statusCode
    responseBody
    duration
  }
}

# Start ngrok
ngrok http 3000

# Use the ngrok URL as your webhook endpoint
# https://abc123.ngrok.io/webhooks/outeract

from fastapi import FastAPI, BackgroundTasks

app = FastAPI()

@app.post("/webhooks/outeract")
async def webhook(request: Request, background_tasks: BackgroundTasks):
    body = await request.body()

    # Verify signature
    if not verify_webhook(body, request.headers):
        return JSONResponse(status_code=401)

    # Queue for async processing
    background_tasks.add_task(process_event, json.loads(body))

    return {"received": True}

processed_events = set()  # Use Redis/DB in production

async def process_event(data):
    event_id = data["event_id"]

    if event_id in processed_events:
        return  # Already processed

    processed_events.add(event_id)
    # Process event...

// Good - specific patterns
["message.inbound", "message.status"]

// Avoid - too broad
["*"]