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

# Create a webhook

> Register a webhook endpoint to receive event notifications.

Webhooks deliver real-time events — enforcement completions, verification changes, policy updates —
to an HTTPS endpoint you control. Register one, send a test delivery, and inspect the delivery log.

```bash theme={null}
curl -X POST https://phosra-api-sandbox-production.up.railway.app/api/v1/webhooks \
  -H "Authorization: Bearer $PHOSRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/hooks/phosra","events":["enforcement.completed"]}'
```

Use [Send a test delivery](/api-reference/webhooks/test-webhook) to fire a sample payload, then read
[List deliveries](/api-reference/webhooks/list-webhook-deliveries) to confirm receipt and debug retries.


## OpenAPI

````yaml POST /webhooks
openapi: 3.1.0
info:
  title: Phosra API
  description: Universal Parental Controls API - Define once, push everywhere
  version: 1.0.0
  contact:
    name: Phosra Developer Support
    url: https://docs.phosra.com
  license:
    name: Proprietary
    url: https://phosra.com/terms
servers:
  - url: https://phosra-api-sandbox-production.up.railway.app/api/v1
    description: >-
      Hosted sandbox — the one canonical, stable, partner-facing testing
      endpoint (seeded demo family + phosra_test_ keys). Default so the inline
      Try it never touches production. Same base the CLI uses.
  - url: https://prodapi.phosra.com/api/v1
    description: Production
  - url: http://localhost:8080/api/v1
    description: Local development
security:
  - BearerAuth: []
paths:
  /webhooks:
    post:
      tags:
        - Webhooks
      summary: Create a webhook subscription
      description: Register a webhook endpoint to receive event notifications.
      operationId: createAWebhookSubscription
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - family_id
                - url
                - events
              properties:
                family_id:
                  type: string
                  format: uuid
                url:
                  type: string
                  description: Webhook URL to receive events
                events:
                  type: array
                  items:
                    type: string
                  description: >-
                    Events to subscribe to (e.g. policy.updated,
                    enforcement.completed)
      responses:
        '201':
          description: Webhook created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
              example:
                id: d41c8f2a-90b7-4e63-a15c-8f0e2b7d3946
                family_id: fcdf4277-ba14-4732-8db5-0369b2c88d8b
                url: https://api.rivera-safety.com/webhooks/phosra
                events:
                  - policy.updated
                  - enforcement.completed
                active: true
                created_at: '2026-06-18T14:32:07Z'
                updated_at: '2026-06-30T09:15:44Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '409':
          $ref: '#/components/responses/Conflict'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
      x-codeSamples:
        - lang: JavaScript
          label: SDK (@phosra/sdk)
          source: |
            import { PhosraClient } from "@phosra/sdk";

            const phosra = new PhosraClient({
              baseUrl: "https://phosra-api-sandbox-production.up.railway.app/api/v1",
              accessToken: process.env.PHOSRA_API_KEY,
            });

            const result = await phosra.webhooks.create({
              family_id: "f0000000-0000-4000-8000-0000000000f1",
              url: "https://yourapp.com/webhooks/phosra",
              events: ["enforcement.completed", "policy.updated"]
            });
            console.log(result);
        - lang: Shell
          label: cURL
          source: >
            curl -sS -X POST
            "https://phosra-api-sandbox-production.up.railway.app/api/v1/webhooks"
            \
              -H "Authorization: Bearer $PHOSRA_API_KEY" \
              -H "Content-Type: application/json" \
              -d '{
              "family_id": "f0000000-0000-4000-8000-0000000000f1",
              "url": "https://yourapp.com/webhooks/phosra",
              "events": [
                "enforcement.completed",
                "policy.updated"
              ]
            }'
        - lang: Python
          label: Python
          source: |
            import os, requests

            BASE = "https://phosra-api-sandbox-production.up.railway.app/api/v1"
            res = requests.post(
                f"{BASE}/webhooks",
                headers={"Authorization": f"Bearer {os.environ['PHOSRA_API_KEY']}"},
                json={
                    "family_id": "f0000000-0000-4000-8000-0000000000f1",
                    "url": "https://yourapp.com/webhooks/phosra",
                    "events": [
                        "enforcement.completed",
                        "policy.updated"
                    ]
                },
            )
            print(res.status_code, res.json())
        - lang: Go
          label: Go
          source: "package main\n\nimport (\n\t\"bytes\"\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n)\n\nfunc main() {\n\tbase := \"https://phosra-api-sandbox-production.up.railway.app/api/v1\"\n\tbody := bytes.NewBufferString(`{\n  \"family_id\": \"f0000000-0000-4000-8000-0000000000f1\",\n  \"url\": \"https://yourapp.com/webhooks/phosra\",\n  \"events\": [\n    \"enforcement.completed\",\n    \"policy.updated\"\n  ]\n}`)\n\treq, _ := http.NewRequest(\"POST\", base+\"/webhooks\", body)\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"PHOSRA_API_KEY\"))\n\treq.Header.Set(\"Content-Type\", \"application/json\")\n\tresp, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer resp.Body.Close()\n\tout, _ := io.ReadAll(resp.Body)\n\tfmt.Println(resp.Status, string(out))\n}\n"
components:
  schemas:
    Webhook:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for this resource.
        family_id:
          type: string
          format: uuid
          description: Identifier of the family this resource belongs to.
        url:
          type: string
          description: HTTPS endpoint that receives POSTed webhook events.
        events:
          type: array
          items:
            type: string
          description: List of event types this webhook subscribes to.
        active:
          type: boolean
          description: Whether the webhook is currently active and receiving deliveries.
        created_at:
          type: string
          format: date-time
          description: RFC 3339 timestamp of when the resource was created.
        updated_at:
          type: string
          format: date-time
          description: RFC 3339 timestamp of the resource's most recent update.
      additionalProperties: true
    Error:
      type: object
      properties:
        error:
          type: string
          description: >-
            Short, stable, machine-readable error class — matches the HTTP
            status text (e.g. `Not Found`).
        message:
          type: string
          description: >-
            Human-readable explanation of what went wrong and, where possible,
            how to fix it.
        code:
          type: integer
          description: Numeric HTTP status code, duplicated in the body for convenience.
      description: Standard error envelope returned for every 4xx and 5xx response.
      example:
        error: Not Found
        message: policy not found
        code: 404
      additionalProperties: true
  responses:
    BadRequest:
      description: >-
        The request was malformed — a required field is missing, a value failed
        validation, or an identifier is not a well-formed UUID.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Bad Request
            message: child_name is required
            code: 400
    Unauthorized:
      description: >-
        Authentication failed. Send a Bearer WorkOS JWT, or a
        `phosra_live_`/`phosra_test_` developer API key, in the `Authorization`
        header.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Unauthorized
            message: missing or invalid Authorization header
            code: 401
    Conflict:
      description: >-
        The request conflicts with the current state of the resource — for
        example, a resource with the same natural key already exists.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Conflict
            message: resource already exists
            code: 409
    RateLimited:
      description: >-
        Too many requests. Back off and retry after the interval given in the
        `Retry-After` response header.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Too Many Requests
            message: rate limit exceeded
            code: 429
    ServerError:
      description: >-
        An unexpected error occurred inside Phosra. The request is safe to retry
        with exponential backoff; contact support if it persists.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Internal Server Error
            message: internal error
            code: 500
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````