> ## Documentation Index > Fetch the complete documentation index at: https://docs.warmr.so/llms.txt > Use this file to discover all available pages before exploring further. # Register a webhook endpoint. Requires webhooks:write. > The 201 body carries the HMAC signing `secret` — returned ONLY in this response, once, at creation (the column is unreadable to clients afterwards; GET/PATCH can never return it again). Store it immediately. The URL must be a public https:// endpoint (an SSRF guard rejects localhost/ private/internal hosts with 422). Omit `events` to subscribe to ALL events; an EXPLICIT `events: []` is rejected with 422 (the empty set means "all", which makes an empty list ambiguous intent). ## OpenAPI ````yaml /api/openapi.yaml post /v1/webhooks openapi: 3.1.0 info: title: Warmr Cloud API version: '1.2' summary: Enqueue and read iPhone-fleet automation work (warmups + posts). description: > The business-facing REST surface for Warmr. **Bring-your-own-fleet**: API keys *enqueue* work and read org-scoped state; your own connected iPhones *execute* it. A server-side **airlock** prevents an API session from ever driving a device. Auth is a two-step flow: exchange a `wk_live_` API key at the exchange endpoint for a short-lived org session, then call `/v1` with `Authorization: Bearer `. Every `/v1` response is wrapped in an envelope `{ "schema": "1.0", ... }`; errors are `{ "schema": "1.0", "error": { "code", "message", "data"? } }`. The exchange endpoint uses a flatter `{ "error": "" }` body. NOTE: the public base URL is deployment-specific and is NOT asserted here. Replace the `app.warmr.so` / `` placeholders below with your deployment's values. license: name: UNLICENSED servers: - url: https://{origin} description: Substitute your Warmr deployment origin. app.warmr.so is a placeholder. variables: origin: default: app.warmr.so description: Your Warmr deployment host, no scheme, e.g. app.example.com security: - bearerAuth: [] tags: - name: auth description: Exchange an API key for an org session. - name: runs description: >- Enqueue and read units of automation work (warm_up or post); your connected iPhones execute them. - name: schedules description: >- Standing recurring post schedules (one account each). The materializer turns them into runs. - name: accounts description: Register and list the social account handles in your org. - name: content description: >- Signed direct-to-storage uploads for post clips (issue → upload → confirm). - name: usage description: Org storage and run counts for a billing period. - name: devices description: The iPhones your runner(s) have reported to the org. - name: webhooks description: >- Subscribe to run.completed / run.failed events and manage deliveries. Opt-in, secret-bearing (webhooks:read / webhooks:write). - name: keys description: >- List your org's API keys — metadata only, the secret is never returned. Opt-in keys:read. - name: health description: Lightweight org-scoped readiness probe. Opt-in health:read. paths: /v1/webhooks: post: tags: - webhooks summary: Register a webhook endpoint. Requires webhooks:write. description: > The 201 body carries the HMAC signing `secret` — returned ONLY in this response, once, at creation (the column is unreadable to clients afterwards; GET/PATCH can never return it again). Store it immediately. The URL must be a public https:// endpoint (an SSRF guard rejects localhost/ private/internal hosts with 422). Omit `events` to subscribe to ALL events; an EXPLICIT `events: []` is rejected with 422 (the empty set means "all", which makes an empty list ambiguous intent). operationId: createWebhook requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateWebhookRequest' responses: '201': description: Webhook created. The `secret` in this body is shown exactly once. content: application/json: schema: $ref: '#/components/schemas/WebhookWithSecretEnvelope' '400': $ref: '#/components/responses/Error' '401': $ref: '#/components/responses/Error' '403': $ref: '#/components/responses/Error' '422': $ref: '#/components/responses/Error' components: schemas: CreateWebhookRequest: type: object required: - url properties: url: type: string format: uri description: >- A public https:// URL (SSRF guard rejects localhost/private/internal hosts). events: type: array minItems: 1 items: type: string description: > Event types to deliver (e.g. run.completed). OMIT to subscribe to ALL events; an explicit empty array is rejected with 422 (the empty set means "all", making [] ambiguous intent). WebhookWithSecretEnvelope: allOf: - $ref: '#/components/schemas/Envelope' - type: object required: - webhook properties: webhook: $ref: '#/components/schemas/WebhookWithSecret' Envelope: type: object required: - schema properties: schema: type: string const: '1.0' WebhookWithSecret: type: object description: > The create projection — the webhook plus its one-time signing secret. Carries NO created_at/updated_at (the create RPC does not return them; GET the webhook for timestamps). required: - webhook_id - url - events - active - secret properties: webhook_id: type: string url: type: string events: type: array items: type: string active: type: boolean secret: type: string description: > The HMAC-SHA256 signing secret. Returned ONLY in the 201 create response — no later call can retrieve it. Store it immediately. ErrorEnvelope: allOf: - $ref: '#/components/schemas/Envelope' - type: object required: - error properties: error: type: object required: - code - message properties: code: type: string message: type: string data: {} responses: Error: description: A /v1 error envelope. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: The access_token from the exchange endpoint. ````