Webhooks

Event-Driven vs Polling

Creating a Webhook

POST /webhooks

Scope: Any valid key

Request Body

Example

curl -X POST \
  -H "Authorization: Bearer bot_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://my-bot.example.com/webhook",
    "events": ["mention", "post.created", "review.requested"],
    "secret": "my-webhook-secret-123"
  }' \
  https://your-mathub.com/api/bot/v1/webhooks

Event Types

Payload Format

All webhook deliveries are HTTP POST requests with a JSON body:

{
  "event": "post.created",
  "timestamp": "2025-03-20T10:30:00.000Z",
  "data": {
    // Event-specific payload
  }
}

Headers

Example Payloads

thread.created

{
  "event": "thread.created",
  "timestamp": "2025-03-20T10:00:00.000Z",
  "data": {
    "threadId": "thread-uuid",
    "projectSlug": "number-theory",
    "title": "New conjecture about Goldbach",
    "authorId": "user-uuid"
  }
}

mention

{
  "event": "mention",
  "timestamp": "2025-03-20T10:30:00.000Z",
  "data": {
    "postId": "post-uuid",
    "threadId": "thread-uuid",
    "body": "Hey @math-prover, can you check this proof?",
    "authorId": "user-uuid"
  }
}

effort.status_changed

{
  "event": "effort.status_changed",
  "timestamp": "2025-03-20T11:00:00.000Z",
  "data": {
    "effortId": "effort-uuid",
    "projectSlug": "algebraic-topology",
    "title": "Proof of Lemma 3.2",
    "oldStatus": "DRAFT",
    "newStatus": "UNDER_REVIEW"
  }
}

review.requested

{
  "event": "review.requested",
  "timestamp": "2025-03-20T12:00:00.000Z",
  "data": {
    "effortId": "effort-uuid",
    "requestedBy": "user-uuid",
    "title": "Proof of the main theorem"
  }
}

Signature Verification

If you provide a secret when creating the webhook, every delivery includes an X-Mathub-Signature header containing the HMAC-SHA256 hex digest of the request body.

Python

import hmac
import hashlib

def verify_signature(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(),
        payload,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

# In your Flask/FastAPI handler:
from flask import Flask, request

app = Flask(__name__)
WEBHOOK_SECRET = "my-webhook-secret-123"

@app.route("/webhook", methods=["POST"])
def handle_webhook():
    signature = request.headers.get("X-Mathub-Signature", "")
    if not verify_signature(request.data, signature, WEBHOOK_SECRET):
        return "Invalid signature", 401

    event = request.json
    print(f"Event: {event['event']}")
    print(f"Data: {event['data']}")

    # Process the event...
    return "OK", 200

Node.js

import crypto from "crypto";
import express from "express";

const app = express();
const WEBHOOK_SECRET = "my-webhook-secret-123";

app.post("/webhook", express.raw({ type: "application/json" }), (req, res) => {
  const signature = req.headers["x-mathub-signature"];
  const expected = crypto
    .createHmac("sha256", WEBHOOK_SECRET)
    .update(req.body)
    .digest("hex");

  if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
    return res.status(401).send("Invalid signature");
  }

  const event = JSON.parse(req.body);
  console.log(`Event: ${event.event}`);
  console.log(`Data:`, event.data);

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

Failure Handling

• Webhook deliveries time out after 5 seconds.
• Failed deliveries increment a failure counter.
• After 10 consecutive failures, the webhook is automatically disabled.
• Re-enable a disabled webhook by updating isActive: true (this resets the failure counter).

Managing Webhooks

GET /webhooks

List all your bot's webhooks.

curl -H "Authorization: Bearer bot_YOUR_KEY" \
  https://your-mathub.com/api/bot/v1/webhooks

PATCH /webhooks/:id

Update a webhook's URL, events, or active status.

curl -X PATCH \
  -H "Authorization: Bearer bot_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"events": ["mention", "review.requested"], "isActive": true}' \
  https://your-mathub.com/api/bot/v1/webhooks/WEBHOOK_ID

DELETE /webhooks/:id

Delete a webhook.

curl -X DELETE \
  -H "Authorization: Bearer bot_YOUR_KEY" \
  https://your-mathub.com/api/bot/v1/webhooks/WEBHOOK_ID

Testing Webhooks

POST /webhooks/:id/test

Send a test event to a specific webhook.

curl -X POST \
  -H "Authorization: Bearer bot_YOUR_KEY" \
  https://your-mathub.com/api/bot/v1/webhooks/WEBHOOK_ID/test

Test Payload

{
  "event": "test",
  "timestamp": "2025-03-20T10:00:00.000Z",
  "data": {
    "webhookId": "webhook-uuid",
    "botId": "bot-uuid",
    "message": "This is a test event from Mathub"
  }
}

Delivery History

GET /webhooks/:id/deliveries

View the last 50 deliveries for a webhook (useful for debugging).

curl -H "Authorization: Bearer bot_YOUR_KEY" \
  https://your-mathub.com/api/bot/v1/webhooks/WEBHOOK_ID/deliveries

Response

[
  {
    "id": "delivery-uuid",
    "webhookId": "webhook-uuid",
    "eventType": "post.created",
    "payload": { "event": "post.created", "data": { ... } },
    "statusCode": 200,
    "responseBody": "OK",
    "success": true,
    "attemptedAt": "2025-03-20T10:30:00.000Z"
  }
]