> ## Documentation Index > Fetch the complete documentation index at: https://docs.formitto.com/llms.txt > Use this file to discover all available pages before exploring further. # Subscribe to an event > Subscribe this API key to an account event. The key must hold the read scope matching the event (form.submitted → read:submissions; booking.created / booking.rescheduled → read:bookings; order.paid → read:orders). The response includes a `secret` shown ONLY here — store it; deliveries are signed and only the secret's hash is retained. ## OpenAPI ````yaml /api/openapi.yaml post /webhooks openapi: 3.1.0 info: title: Formitto API version: 1.0.0 description: > The Formitto public API (v1). Read and manage your forms, submissions, calendars, bookings, shop widgets, and orders programmatically. Authenticate with an API key created in the Formitto dashboard (Settings → API keys). Pass it as a Bearer token: `Authorization: Bearer fmt_live_...`. Keys are scoped — a key only reaches the endpoints its scopes allow (e.g. `read:forms`, `write:submissions`). All responses are JSON. List endpoints return a `{ data, pagination }` envelope; single-resource endpoints return the object directly. Requests are rate-limited per API key; see the `X-RateLimit-*` response headers. contact: name: Formitto Support url: https://formitto.com license: name: Proprietary url: https://formitto.com/terms servers: - url: https://formitto.com/v1 description: Production security: - bearerAuth: [] tags: - name: forms description: Create, read, update, and archive forms. - name: submissions description: Read and programmatically ingest form submissions. - name: calendars description: Read calendar widgets. - name: bookings description: Read calendar bookings. - name: ecommerce description: Read shop widgets. - name: orders description: Read shop orders. - name: webhooks description: Manage event subscriptions (REST Hooks) for integrations. paths: /webhooks: post: tags: - webhooks summary: Subscribe to an event description: > Subscribe this API key to an account event. The key must hold the read scope matching the event (form.submitted → read:submissions; booking.created / booking.rescheduled → read:bookings; order.paid → read:orders). The response includes a `secret` shown ONLY here — store it; deliveries are signed and only the secret's hash is retained. operationId: createWebhookSubscription requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/WebhookSubscriptionCreate' responses: '201': description: The created subscription, including the one-time secret. headers: X-RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/RateLimitReset' content: application/json: schema: $ref: '#/components/schemas/WebhookSubscriptionCreated' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/ServerError' components: schemas: WebhookSubscriptionCreate: type: object required: - event - target_url properties: event: type: string description: >- The account event to subscribe to. The key must hold the matching read scope. enum: - form.submitted - booking.created - booking.rescheduled - order.paid target_url: type: string format: uri description: The HTTPS destination Formitto POSTs each matching event to. WebhookSubscriptionCreated: type: object description: > A newly created subscription. `secret` is shown ONCE here and never again — store it to verify delivery signatures. required: - id - event - target_url - secret - created_at properties: id: type: string event: type: string enum: - form.submitted - booking.created - booking.rescheduled - order.paid target_url: type: string format: uri secret: type: string description: The one-time plaintext signing secret. Not retrievable later. created_at: type: string format: date-time Error: type: object description: > Standard error envelope. `code` is a stable machine-readable string (e.g. invalid_api_key, insufficient_scope, not_found, rate_limited, domain_required, forbidden_field). Some errors carry extra context fields (candidates, required, fields, invalid, retryAfter). required: - error additionalProperties: true properties: error: type: string description: Human-readable message. code: type: string description: Stable machine-readable error code. headers: RateLimitLimit: description: The per-API-key request budget for the current 1-hour window. schema: type: integer RateLimitRemaining: description: Requests remaining in the current window after this request. schema: type: integer RateLimitReset: description: Unix timestamp (seconds) at which the rate-limit window resets. schema: type: integer RetryAfter: description: Seconds to wait before retrying. Present on 429 responses. schema: type: integer responses: BadRequest: description: >- The request was invalid (validation error, bad domain, forbidden field, etc.). content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: The API key is missing, malformed, revoked, or expired. content: application/json: schema: $ref: '#/components/schemas/Error' Forbidden: description: The API key is valid but lacks the scope this endpoint requires. headers: X-RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/RateLimitReset' content: application/json: schema: $ref: '#/components/schemas/Error' RateLimited: description: The per-API-key request budget for the current window is exhausted. headers: X-RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/RateLimitReset' Retry-After: $ref: '#/components/headers/RetryAfter' content: application/json: schema: $ref: '#/components/schemas/Error' ServerError: description: An unexpected server error. content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: fmt_live_* description: > A Formitto API key created in the dashboard (Settings → API keys). Pass it as `Authorization: Bearer fmt_live_...`. ````