WebhookSubscription

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/craaft-io/json-schema/craaft-io-webhook-subscription-schema.json",
  "title": "WebhookSubscription",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/craaft-io-webhooks-api-openapi.yml#/components/schemas/WebhookSubscription",
  "type": "object",
  "required": [
    "id",
    "endpointId",
    "url",
    "description",
    "format",
    "events",
    "active",
    "createdAt"
  ],
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "description": "Subscription id (the handle for update/delete)"
    },
    "endpointId": {
      "type": "string",
      "format": "uuid",
      "description": "Endpoint id at the workspace level"
    },
    "url": {
      "type": "string",
      "format": "uri",
      "description": "The target URL for deliveries"
    },
    "secret": {
      "type": "string",
      "description": "HMAC signing secret for 'craaft' deliveries (X-Craaft-Signature). Returned only when the webhook is created, so copy it then; to get a new one, delete the webhook and add it again. Slack/Discord deliveries are unsigned and ignore it."
    },
    "description": {
      "type": "string",
      "description": "Optional label"
    },
    "format": {
      "type": "string",
      "enum": [
        "craaft",
        "slack",
        "discord"
      ],
      "description": "Delivery format (craaft=signed JSON envelope; slack/discord=message POST)"
    },
    "events": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Event filter (empty=all events; non-empty=only listed events)"
    },
    "active": {
      "type": "boolean"
    },
    "createdAt": {
      "type": "string",
      "format": "date-time"
    },
    "recentDeliveries": {
      "type": "array",
      "description": "Last few delivery attempts (most recent first), capped at 10",
      "items": {
        "$ref": "#/$defs/WebhookDelivery"
      }
    }
  },
  "$defs": {
    "WebhookDelivery": {
      "type": "object",
      "required": [
        "event",
        "status",
        "statusCode",
        "attempts",
        "error",
        "createdAt"
      ],
      "properties": {
        "event": {
          "type": "string",
          "description": "The broadcast event name (e.g. 'card.created')"
        },
        "status": {
          "type": "string",
          "enum": [
            "delivered",
            "failed"
          ],
          "description": "Delivery outcome"
        },
        "statusCode": {
          "type": "integer",
          "description": "HTTP status code from the webhook URL"
        },
        "attempts": {
          "type": "integer",
          "description": "Number of delivery attempts"
        },
        "error": {
          "type": "string",
          "description": "Error message when status is failed; empty string on success (never null)"
        },
        "createdAt": {
          "type": "string",
          "format": "date-time"
        }
      }
    }
  }
}