Webhooks

​

Setting up a webhook

curl -X POST https://api.moda.app/v1/tasks \
  -H "Authorization: Bearer moda_live_abc123..." \
  -H "Moda-Version: 2026-05-01" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Create a modern SaaS landing page",
    "callback_url": "https://your-server.com/webhooks/moda"
  }'

​

Event types

​

Webhook payload

{
  "id": "evt_01HT9WK8N3M2J4A5Z6P7Q8R9TV",
  "type": "task.succeeded",
  "created": "2026-04-15T12:01:00+00:00",
  "api_version": "2026-05-01",
  "data": {
    "id": "task_01HT9WK8N3M2J4A5Z6P7Q8R9TV",
    "kind": "design",
    "status": "succeeded",
    "created_at": "2026-04-15T12:00:00+00:00",
    "started_at": "2026-04-15T12:00:02+00:00",
    "completed_at": "2026-04-15T12:01:00+00:00",
    "progress": null,
    "attempt": 1,
    "max_attempts": 3,
    "input": { "prompt": "Create a modern SaaS landing page" },
    "result": {
      "canvas_id": "cvs_01HT9WK8N3M2J4A5Z6P7Q8R9TV",
      "canvas_url": "https://app.moda.com/canvas/..."
    },
    "error": null,
    "credits": { "credits_used": 5, "credits_remaining": 12 },
    "links": {
      "self": "/v1/tasks/task_01HT9WK8N3M2J4A5Z6P7Q8R9TV",
      "events": null,
      "cancel": null,
      "canvas": "https://app.moda.com/canvas/..."
    },
    "retry_after_ms": null
  }
}

​

Envelope fields

​

Verifying webhook signatures

1. Extract the timestamp from the X-Webhook-Timestamp header
2. Concatenate: {timestamp}.{raw_request_body}
3. Compute HMAC-SHA256(signing_secret, concatenated_string)
4. Compare the result with the signature value after the v1= prefix

​

Verification example

import crypto from 'node:crypto';

function verifyWebhook(signingSecret, requestBody, signatureHeader, timestampHeader) {
  const message = `${timestampHeader}.${requestBody}`;
  const expected = crypto.createHmac('sha256', signingSecret).update(message).digest();
  const received = Buffer.from(signatureHeader.replace('v1=', ''), 'hex');

  // timingSafeEqual throws when buffer lengths differ; check first so a
  // malformed signature can't crash the handler.
  if (expected.length !== received.length) {
    return false;
  }
  return crypto.timingSafeEqual(expected, received);
}

import hashlib
import hmac

def verify_webhook(
    signing_secret: str,
    request_body: bytes,
    signature_header: str,
    timestamp_header: str,
) -> bool:
    message = f"{timestamp_header}.{request_body.decode()}"
    expected = hmac.new(
        signing_secret.encode(), message.encode(), hashlib.sha256
    ).hexdigest()
    received = signature_header.removeprefix("v1=")

    return hmac.compare_digest(expected, received)

​

Retry behavior

​

Best practices

• Return 200 quickly. Process the webhook payload asynchronously to avoid timeouts. Acknowledge receipt first, then handle the event.
• Verify signatures. Always validate the X-Webhook-Signature header before trusting the payload.
• Check timestamps. Reject webhooks with timestamps more than 5 minutes old to prevent replay attacks.
• Handle duplicates. In rare cases, the same event may be delivered more than once. Use the envelope id (evt_…) as an idempotency key — it’s stable across retries of the same event.
• Use HTTPS. Your callback_url must use HTTPS to protect the payload in transit.

​

Delivery log & manual replay

• List deliveries: GET /webhook_deliveries (reference) — cursor-paginated, filterable by event type, status, API key, and date range. Response rows include the target URL, HTTP status code, response body excerpt (first 2KB), and attempt count.
• Replay a delivery: POST /webhook_deliveries/{id}/redeliver (reference) — queues a fresh attempt with the original payload to the original URL. Returns 202 with the new delivery’s ID so you can follow it.