> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mobilerun.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Register a webhook subscription

> Creates a webhook subscription with a delivery URL and an optional list of event types to subscribe to (defaults to all when omitted). The response includes the generated signing secret, which is returned only once at creation time and cannot be retrieved later.



## OpenAPI

````yaml /api-reference/webhooks.yaml post /webhooks
openapi: 3.1.0
info:
  title: Webhooks
  version: v1
servers:
  - url: https://api.mobilerun.ai
    description: Droidrun Cloud API
security:
  - bearerAuth: []
paths:
  /webhooks:
    post:
      tags:
        - Webhooks
      summary: Register a webhook subscription
      description: >-
        Creates a webhook subscription with a delivery URL and an optional list
        of event types to subscribe to (defaults to all when omitted). The
        response includes the generated signing secret, which is returned only
        once at creation time and cannot be retrieved later.
      operationId: createWebhook
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                url:
                  type: string
                  maxLength: 2048
                  format: uri
                  example: https://example.com/webhooks/droidrun
                eventTypes:
                  type: array
                  items:
                    type: string
                    minLength: 1
                    maxLength: 256
                  maxItems: 100
                  example:
                    - task.run.completed
                    - task.run.failed
                description:
                  type: string
                  maxLength: 500
              required:
                - url
      responses:
        '201':
          description: Webhook created (secret shown once)
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        format: uuid
                      url:
                        type: string
                      eventTypes:
                        type: array
                        items:
                          type: string
                      state:
                        type: string
                        enum:
                          - ACTIVE
                          - DISABLED
                          - DELETED
                      health:
                        type: string
                        enum:
                          - healthy
                          - failing
                          - blocked
                        description: >-
                          System-observed delivery health. `blocked` endpoints
                          are auto-disabled after sustained failure; PATCH
                          state=ACTIVE to re-enable.
                      blockedAt:
                        type:
                          - string
                          - 'null'
                      blockedReason:
                        type:
                          - string
                          - 'null'
                      signingEnabled:
                        type: boolean
                      description:
                        type:
                          - string
                          - 'null'
                      createdAt:
                        type: string
                      updatedAt:
                        type: string
                      secret:
                        type: string
                        description: Signing secret — shown only once. Store it now.
                    required:
                      - id
                      - url
                      - eventTypes
                      - state
                      - health
                      - blockedAt
                      - blockedReason
                      - signingEnabled
                      - description
                      - createdAt
                      - updatedAt
                      - secret
                required:
                  - data
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '409':
          description: Conflict
        '500':
          description: Internal Server Error
      x-codeSamples:
        - lang: JavaScript
          source: >-
            import Mobilerun from '@mobilerun/sdk';


            const client = new Mobilerun({
              apiKey: process.env['MOBILERUN_CLOUD_API_KEY'], // This is the default and can be omitted
            });


            const webhook = await client.webhooks.create({ url:
            'https://example.com/webhooks/droidrun' });


            console.log(webhook.data);
        - lang: Python
          source: |-
            import os
            from mobilerun_sdk import Mobilerun

            client = Mobilerun(
                api_key=os.environ.get("MOBILERUN_CLOUD_API_KEY"),  # This is the default and can be omitted
            )
            webhook = client.webhooks.create(
                url="https://example.com/webhooks/droidrun",
            )
            print(webhook.data)
        - lang: Go
          source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/stainless-sdks/droidrun-cloud-go\"\n\t\"github.com/stainless-sdks/droidrun-cloud-go/option\"\n)\n\nfunc main() {\n\tclient := mobileruncloud.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\twebhook, err := client.Webhooks.New(context.TODO(), mobileruncloud.WebhookNewParams{\n\t\tURL: \"https://example.com/webhooks/droidrun\",\n\t})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", webhook.Data)\n}\n"
        - lang: CLI
          source: |-
            mobilerun-cloud webhooks create \
              --api-key 'My API Key' \
              --url https://example.com/webhooks/droidrun
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: Opaque
      description: Bearer token via Authorization header

````