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

# Register a notification webhook

> Register a webhook for the organization, provision its signing secret, and
subscribe it to the given topics — all in one atomic append. The signing secret
is returned once in this response and never again, so the caller must store it
now. A malformed or disallowed URL (non-https outside dev, or an SSRF-blocked
address) is rejected and nothing is created.

Each call registers a new, independent endpoint; it is not idempotent — a retried
or repeated POST with the same URL creates a second webhook with its own secret,
so callers that retry must guard against duplicates. The response is built from
the just-committed create rather than re-read, so a transient read failure can
never strand the one-time secret.



## OpenAPI

````yaml https://app.podero.com/api/partners/v2.0/openapi.json post /api/partners/v2.0/org/{org_id}/notifications/webhooks
openapi: 3.1.0
info:
  title: Podero Partner API
  version: '2.0'
  description: >-
    This API provides a unified interaction point for Podero's partner
    companies.


    The goal of this API is to give partners easily integratable endpoints that
    don't require extensive software

    development. For this reason, the endpoints focus around user and device
    management, setting of preferences

    and high level device controls.


    While direct control of devices is implemented for special use cases such as
    pause power, we abstract away low level

    direct device steering so developers and partners can focus on delivering
    maximum value to end users.
  termsOfService: https://www.podero.com/terms-and-conditions
servers: []
security: []
paths:
  /api/partners/v2.0/org/{org_id}/notifications/webhooks:
    post:
      tags:
        - Notification Webhooks
      summary: Register a notification webhook
      description: >-
        Register a webhook for the organization, provision its signing secret,
        and

        subscribe it to the given topics — all in one atomic append. The signing
        secret

        is returned once in this response and never again, so the caller must
        store it

        now. A malformed or disallowed URL (non-https outside dev, or an
        SSRF-blocked

        address) is rejected and nothing is created.


        Each call registers a new, independent endpoint; it is not idempotent —
        a retried

        or repeated POST with the same URL creates a second webhook with its own
        secret,

        so callers that retry must guard against duplicates. The response is
        built from

        the just-committed create rather than re-read, so a transient read
        failure can

        never strand the one-time secret.
      operationId: >-
        integrations_api_api_v2_organizations_notifications_webhooks_router_create_webhook
      parameters:
        - in: path
          name: org_id
          schema:
            description: The organization ID of the user's organization
            format: uuid
            title: Org Id
            type: string
          required: true
          description: The organization ID of the user's organization
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookCreateInput'
        required: true
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookCreatedOutput'
      security:
        - OAuth2: []
components:
  schemas:
    WebhookCreateInput:
      description: >-
        Register a webhook: an https endpoint URL and the topics it subscribes
        to.

        Topics are validated against the catalogue — an unknown topic is
        rejected.
      properties:
        url:
          title: Url
          type: string
        topics:
          default: []
          items:
            $ref: '#/components/schemas/Topic'
          title: Topics
          type: array
      required:
        - url
      title: WebhookCreateInput
      type: object
    WebhookCreatedOutput:
      description: >-
        The response to a create: the new webhook plus its signing secret. The
        secret

        is returned **once, here only** — it is never retrievable again, so the
        caller

        must store it now.
      properties:
        webhook_id:
          format: uuid
          title: Webhook Id
          type: string
        url:
          title: Url
          type: string
        enabled:
          title: Enabled
          type: boolean
        topics:
          items:
            $ref: '#/components/schemas/Topic'
          title: Topics
          type: array
        signing_secret:
          title: Signing Secret
          type: string
      required:
        - webhook_id
        - url
        - enabled
        - topics
        - signing_secret
      title: WebhookCreatedOutput
      type: object
    Topic:
      enum:
        - device.action_required
        - device.information
      title: Topic
      type: string
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        password:
          tokenUrl: /api/partners/v2.0/auth/token
          scopes: {}
        clientCredentials:
          tokenUrl: /api/partners/v2.0/auth/token
          scopes: {}

````