> ## Documentation Index > Fetch the complete documentation index at: https://docs.mareaalcalina.com/llms.txt > Use this file to discover all available pages before exploring further. # Use this when you want to register a webhook endpoint that receives one or more event types (`user.verified`, `user.cancelled`, `order.*`). > Creates a webhook endpoint as a first-class object. The returned `signingSecret` is the only time the secret is visible — store it now; rotate via `POST /v1/webhook_endpoints/{id}/rotate-secret` if lost. Per-event subscription is controlled by `subscribedEvents`. A developer endpoint can subscribe to `order.*` events from any storefront the caller bootstrapped — Marea resolves the merchant → developer chain at dispatch time, so one endpoint covers every storefront. Hard caps: 16 endpoints per account; URL ≤2048 chars; HTTPS only; rejects loopback / private / metadata hostnames. ## OpenAPI ````yaml /openapi.json post /v1/webhook_endpoints openapi: 3.1.0 info: title: Marea Alcalina API version: 1.0.0 servers: - url: https://api.mareaalcalina.com security: [] paths: /v1/webhook_endpoints: post: summary: >- Use this when you want to register a webhook endpoint that receives one or more event types (`user.verified`, `user.cancelled`, `order.*`). description: >- Creates a webhook endpoint as a first-class object. The returned `signingSecret` is the only time the secret is visible — store it now; rotate via `POST /v1/webhook_endpoints/{id}/rotate-secret` if lost. Per-event subscription is controlled by `subscribedEvents`. A developer endpoint can subscribe to `order.*` events from any storefront the caller bootstrapped — Marea resolves the merchant → developer chain at dispatch time, so one endpoint covers every storefront. Hard caps: 16 endpoints per account; URL ≤2048 chars; HTTPS only; rejects loopback / private / metadata hostnames. operationId: createWebhookEndpoint requestBody: required: true content: application/json: schema: type: object properties: url: type: string maxLength: 2048 description: type: - string - 'null' maxLength: 256 enabled: type: - boolean - 'null' subscribedEvents: type: array items: type: string enum: - user.verified - user.cancelled - order.created - order.status_updated - order.paid minItems: 1 maxItems: 5 required: - url - subscribedEvents responses: '201': description: Created content: application/json: schema: type: object properties: endpointId: type: string scope: type: string enum: - developer - merchant url: type: string description: type: - string - 'null' enabled: type: boolean subscribedEvents: type: array items: type: string enum: - user.verified - user.cancelled - order.created - order.status_updated - order.paid signingSecretVersion: type: integer createdAt: type: string updatedAt: type: string lastDeliveryAt: type: - string - 'null' lastDeliveryStatus: type: - string - 'null' enum: - success - failure consecutiveFailures: type: integer minimum: 0 signingSecret: type: string pattern: ^[0-9a-f]{64}$ required: - endpointId - scope - url - description - enabled - subscribedEvents - signingSecretVersion - createdAt - updatedAt - lastDeliveryAt - lastDeliveryStatus - consecutiveFailures - signingSecret '400': description: §9.6 error envelope content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' '401': description: §9.6 error envelope content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' '403': description: §9.6 error envelope content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' '404': description: §9.6 error envelope content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' '409': description: §9.6 error envelope content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' '410': description: §9.6 error envelope content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' '413': description: §9.6 error envelope content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' '429': description: §9.6 error envelope content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' '500': description: §9.6 error envelope content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' '503': description: §9.6 error envelope content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' security: - BearerAuth: [] components: schemas: ApiErrorResponse: type: object properties: error: $ref: '#/components/schemas/ApiErrorBody' required: - error description: §9.6 uniform error envelope. Every non-2xx response uses this shape. ApiErrorBody: type: object properties: type: type: string enum: - rate_limited - invalid_request - auth - not_found - plan_limit - internal - conflict - idempotency_conflict - service_unavailable - tos_not_accepted description: High-level error category. Agents branch on this. example: auth code: type: string description: Stable machine-readable code. example: missing_authorization message: type: string description: Human-readable, localized via Accept-Language. doc: type: string description: Link to the error reference in the docs. example: https://docs.mareaalcalina.com/concepts/errors param: type: - string - 'null' requestId: type: string example: req_30a9358b-70bd-44f3-aa5d-8983b558ad84 recoverable: type: boolean retryAfterMs: type: - integer - 'null' nextActions: type: array items: $ref: '#/components/schemas/ApiNextAction' upgrade: $ref: '#/components/schemas/ApiErrorUpgrade' requiredScopes: type: array items: type: string heldScopes: type: array items: type: string required: - type - code - message - doc - param - requestId - recoverable - retryAfterMs - nextActions - upgrade ApiNextAction: type: object properties: label: type: string example: Validate the JSON before retrying. method: type: - string - 'null' example: null url: type: - string - 'null' example: null required: - label - method - url description: A concrete action the agent can offer the user. ApiErrorUpgrade: type: - object - 'null' properties: currentPlan: type: string example: free requiredPlan: type: string example: pro upgradeUrl: type: string example: >- https://mareaalcalina.com/menus/profile?changePlan=basic&frequency=monthly&planSource=api previewUrl: type: string description: Optional preview link the agent can surface. required: - currentPlan - requiredPlan - upgradeUrl securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: mk_dev_* | mk_user_* ````