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

# Create Webhook

> Register a webhook endpoint to receive event notifications from your Telegent account. Use this to subscribe to events such as order updates, message status changes, or other platform activity, with optional Basic or Token authentication for callback security.

**Available subscribable events:** `Order_Update`, `New_Sms`, `Call_Completed`, `Call_On_Hold`, `Call_Recording`, `Call_In_Progress`, `Call_Ringing`

After you register, Telegent POSTs a JSON payload to your `Url` each time a subscribed event fires. See [Webhook Event Payloads](/best-practices/reference#43-receiving-events--webhook-payloads) for the delivered body shape per event type.



## OpenAPI

````yaml /api-reference/openapi.json post /v1.0/webhook/create
openapi: 3.0.3
info:
  title: mPaaS Core APIs
  version: 1.0.8
  description: >-
    The Telegent mPaaS (Mobile Platform as a Service) API gives you full
    programmatic control over mobile phone numbers, messaging, voice routing,
    subscribers, and account management. Use these APIs to provision MVNO and
    IoT numbers, send and receive SMS/MMS, configure intelligent call routing,
    manage subscriber accounts, and apply AI Guardian controls. All requests
    require a Bearer token obtained from the Authentication endpoint. For
    support, visit https://support.telegent.com/support/home
  contact:
    name: Support
    email: support@telegent.com
  termsOfService: https://telegent.com/terms
  license:
    name: Use under LICX
    url: https://telegent.com/license
servers:
  - url: https://api.telegent.com
security:
  - BearerAuth: []
tags:
  - name: OAuth2
  - name: AI Guardian
  - name: Accounts
  - name: Distributors
  - name: Message
  - name: Numbers
  - name: Voicemail
  - name: Packages
  - name: Products
  - name: Schedules
  - name: Services
  - name: Sims
  - name: Subscribers
  - name: Subscriptions
  - name: Voice
  - name: Workgroups
paths:
  /v1.0/webhook/create:
    post:
      tags:
        - Webhooks
      summary: Create Webhook
      description: >-
        Register a webhook endpoint to receive event notifications from your
        Telegent account. Use this to subscribe to events such as order updates,
        message status changes, or other platform activity, with optional Basic
        or Token authentication for callback security.


        **Available subscribable events:** `Order_Update`, `New_Sms`,
        `Call_Completed`, `Call_On_Hold`, `Call_Recording`, `Call_In_Progress`,
        `Call_Ringing`


        After you register, Telegent POSTs a JSON payload to your `Url` each
        time a subscribed event fires. See [Webhook Event
        Payloads](/best-practices/reference#43-receiving-events--webhook-payloads)
        for the delivered body shape per event type.
      requestBody:
        description: Webhooks object
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Webhook_Request'
          text/json:
            schema:
              $ref: '#/components/schemas/Webhook_Request'
          application/*+json:
            schema:
              $ref: '#/components/schemas/Webhook_Request'
      responses:
        '200':
          description: Success
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/Webhook_Result'
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook_Result'
            text/json:
              schema:
                $ref: '#/components/schemas/Webhook_Result'
        '400':
          description: Bad Request
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/BadRequest_Result'
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequest_Result'
              examples:
                example:
                  value:
                    StatusCode: 400
                    Message: >-
                      Bad request: one or more required fields are missing or
                      contain an invalid value.
            text/json:
              schema:
                $ref: '#/components/schemas/BadRequest_Result'
        '401':
          description: Unauthorized
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/Unauthorized_Result'
            application/json:
              schema:
                $ref: '#/components/schemas/Unauthorized_Result'
              examples:
                example:
                  value:
                    StatusCode: 401
                    Message: >-
                      Unauthorized: Bearer token is missing, expired, or
                      invalid. Re-authenticate via POST /v1.0/oauth2/tokens.
            text/json:
              schema:
                $ref: '#/components/schemas/Unauthorized_Result'
        '403':
          description: Forbidden
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/Forbidden_Result'
            application/json:
              schema:
                $ref: '#/components/schemas/Forbidden_Result'
              examples:
                example:
                  value:
                    StatusCode: 403
                    Message: >-
                      Forbidden: your token does not have permission to access
                      this resource. Check the ApiEndpoint scope.
            text/json:
              schema:
                $ref: '#/components/schemas/Forbidden_Result'
        '404':
          description: Not Found
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/NotFound_Result'
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound_Result'
              examples:
                example:
                  value:
                    StatusCode: 404
                    Message: >-
                      Not found: the requested resource does not exist or
                      belongs to a different account.
            text/json:
              schema:
                $ref: '#/components/schemas/NotFound_Result'
        '405':
          description: Method Not Allowed
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/MethodNotAllowed_Result'
            application/json:
              schema:
                $ref: '#/components/schemas/MethodNotAllowed_Result'
              examples:
                example:
                  value:
                    StatusCode: 405
                    Message: >-
                      Method not allowed: verify the HTTP method required for
                      this endpoint.
            text/json:
              schema:
                $ref: '#/components/schemas/MethodNotAllowed_Result'
        '408':
          description: Request Timeout
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/RequestTimeout_Result'
            application/json:
              schema:
                $ref: '#/components/schemas/RequestTimeout_Result'
              examples:
                example:
                  value:
                    StatusCode: 408
                    Message: >-
                      Request timeout: the server did not receive a complete
                      request within the allowed time. Retry with exponential
                      backoff.
            text/json:
              schema:
                $ref: '#/components/schemas/RequestTimeout_Result'
        '429':
          description: Too Many Requests
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/TooManyRequests_Result'
            application/json:
              schema:
                $ref: '#/components/schemas/TooManyRequests_Result'
              examples:
                example:
                  value:
                    StatusCode: 429
                    Message: >-
                      Too many requests: rate limit exceeded. Slow your request
                      cadence and retry after a short delay.
            text/json:
              schema:
                $ref: '#/components/schemas/TooManyRequests_Result'
        '500':
          description: Server Error
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/InternalServerError_Result'
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerError_Result'
              examples:
                example:
                  value:
                    StatusCode: 500
                    Message: >-
                      Internal server error: an unexpected error occurred. If
                      the problem persists contact support@telegent.com.
            text/json:
              schema:
                $ref: '#/components/schemas/InternalServerError_Result'
        '503':
          description: Service Unavailable
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ServiceUnavailable_Result'
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceUnavailable_Result'
              examples:
                example:
                  value:
                    StatusCode: 503
                    Message: >-
                      Service unavailable: the API is temporarily unavailable.
                      Retry after a short delay.
            text/json:
              schema:
                $ref: '#/components/schemas/ServiceUnavailable_Result'
        '504':
          description: Gateway Timeout
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/GatewayTimeout_Result'
            application/json:
              schema:
                $ref: '#/components/schemas/GatewayTimeout_Result'
              examples:
                example:
                  value:
                    StatusCode: 504
                    Message: >-
                      Gateway timeout: an upstream service did not respond in
                      time. Retry with exponential backoff.
            text/json:
              schema:
                $ref: '#/components/schemas/GatewayTimeout_Result'
      x-codeSamples:
        - lang: JSON
          source: |-
            {
              "AccountId": "AID-1234567",
              "WebhookUrl": "https://api.example.com/telegent/events",
              "Method": "POST",
              "DataFormat": "json",
              "AuthenticationType": "Basic",
              "AuthenticationUsername": "webhook_user",
              "AuthenticationPassword": "s3cureP@ss",
              "AuthenticationToken": "",
              "SubscribedEvents": "Order_Update"
            }
        - lang: cURL
          source: |-
            curl -X POST https://api.telegent.com/v1.0/webhook/create \
              -H "Authorization: Bearer <token>" \
              -H "Content-Type: application/json" \
              -d '{
                "AccountId": "AID-1234567",
                "WebhookUrl": "https://api.example.com/telegent/events",
                "Method": "POST",
                "DataFormat": "json",
                "AuthenticationType": "Basic",
                "AuthenticationUsername": "webhook_user",
                "AuthenticationPassword": "s3cureP@ss",
                "AuthenticationToken": "",
                "SubscribedEvents": "Order_Update"
              }'
components:
  schemas:
    Webhook_Request:
      type: object
      properties:
        AccountId:
          maxLength: 100
          type: string
          nullable: true
          description: >-
            Your Telegent account identifier in the format `AID-XXXXXXX`. Max
            100 characters.
        WebhookUrl:
          maxLength: 255
          type: string
          nullable: true
          description: >-
            The HTTPS URL Telegent will call when subscribed events fire. Max
            255 characters.
        Method:
          maxLength: 10
          type: string
          nullable: true
          description: >-
            HTTP method Telegent should use when invoking the webhook, typically
            `POST` or `PUT`. Max 10 characters.
        DataFormat:
          maxLength: 50
          type: string
          nullable: true
          description: >-
            Payload format sent to your endpoint, such as `json` or `xml`. Max
            50 characters.
        AuthenticationType:
          maxLength: 10
          type: string
          nullable: true
          description: >-
            Authentication scheme used when calling the webhook: `None`,
            `Basic`, or `Token`. Max 10 characters.
        AuthenticationUsername:
          maxLength: 255
          type: string
          nullable: true
          description: >-
            Username for Basic authentication. Required when
            `AuthenticationType` is `Basic`. Max 255 characters.
        AuthenticationPassword:
          maxLength: 255
          type: string
          nullable: true
          description: >-
            Password for Basic authentication. Required when
            `AuthenticationType` is `Basic`. Max 255 characters.
        AuthenticationToken:
          maxLength: 255
          type: string
          nullable: true
          description: >-
            Bearer token sent in the `Authorization` header. Required when
            `AuthenticationType` is `Token`. Max 255 characters.
        SubscribedEvents:
          maxLength: 255
          type: string
          nullable: true
          description: >-
            Comma-separated list of events to subscribe to. Available events:
            `Order_Update`, `New_Sms`, `Call_Completed`, `Call_On_Hold`,
            `Call_Recording`, `Call_In_Progress`, `Call_Ringing`. Max 255
            characters.
      additionalProperties: false
    Webhook_Result:
      type: object
      properties:
        AccountId:
          maxLength: 100
          type: string
          nullable: true
        WebhookUrl:
          maxLength: 255
          type: string
          nullable: true
        Method:
          maxLength: 10
          type: string
          nullable: true
        DataFormat:
          maxLength: 50
          type: string
          nullable: true
        AuthenticationType:
          maxLength: 10
          type: string
          nullable: true
        AuthenticationUsername:
          maxLength: 255
          type: string
          nullable: true
        AuthenticationPassword:
          maxLength: 255
          type: string
          nullable: true
        AuthenticationToken:
          maxLength: 255
          type: string
          nullable: true
        SubscribedEvents:
          maxLength: 255
          type: string
          nullable: true
        WebhookId:
          type: string
          nullable: true
        Active:
          type: boolean
          nullable: true
      additionalProperties: false
    BadRequest_Result:
      required:
        - StatusCode
      type: object
      properties:
        StatusCode:
          type: integer
          format: int32
        Message:
          type: string
          nullable: true
      additionalProperties: false
    Unauthorized_Result:
      required:
        - StatusCode
      type: object
      properties:
        StatusCode:
          type: integer
          format: int32
        Message:
          type: string
          nullable: true
      additionalProperties: false
    Forbidden_Result:
      required:
        - StatusCode
      type: object
      properties:
        StatusCode:
          type: integer
          format: int32
        Message:
          type: string
          nullable: true
      additionalProperties: false
    NotFound_Result:
      required:
        - StatusCode
      type: object
      properties:
        StatusCode:
          type: integer
          format: int32
        Message:
          type: string
          nullable: true
      additionalProperties: false
    MethodNotAllowed_Result:
      required:
        - StatusCode
      type: object
      properties:
        StatusCode:
          type: integer
          format: int32
        Message:
          type: string
          nullable: true
      additionalProperties: false
    RequestTimeout_Result:
      required:
        - StatusCode
      type: object
      properties:
        StatusCode:
          type: integer
          format: int32
        Message:
          type: string
          nullable: true
      additionalProperties: false
    TooManyRequests_Result:
      required:
        - StatusCode
      type: object
      properties:
        StatusCode:
          type: integer
          format: int32
        Message:
          type: string
          nullable: true
      additionalProperties: false
    InternalServerError_Result:
      required:
        - StatusCode
      type: object
      properties:
        StatusCode:
          type: integer
          format: int32
        Message:
          type: string
          nullable: true
      additionalProperties: false
    ServiceUnavailable_Result:
      required:
        - StatusCode
      type: object
      properties:
        StatusCode:
          type: integer
          format: int32
        Message:
          type: string
          nullable: true
      additionalProperties: false
    GatewayTimeout_Result:
      required:
        - StatusCode
      type: object
      properties:
        StatusCode:
          type: integer
          format: int32
        Message:
          type: string
          nullable: true
      additionalProperties: false

````