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

# Register new webhook

> Register a new webhook which will be called on a specific event. See the WebhookCallback model. (Permitted scopes: **fax:all:edit**, **fax:webhook:edit**)

<RequestExample>
  ```js NodeJS SDK theme={null}
  const axios = require('axios');
  const WebhooksApiFp = require('@alohi/faxplus-api').WebhooksApiFp;
  const Configuration = require('@alohi/faxplus-api').Configuration;

  const config = new Configuration({
      accessToken: accessToken,
      basePath: 'https://restapi.fax.plus/v3',
      // Header required only when using the OAuth2 token scheme
      baseOptions: {
          headers: {
            "x-fax-clientid": clientId,
          }
      }
  });

  async function createWebhook() {
      const reqParams = {
          "webhook": {
              "target": "http://myapp.com/fax_received",
              "event": "fax_received"
          }
      }
      const req = await WebhooksApiFp(config).createWebhook(reqParams);
      const resp = await req(axios);
  }

  createWebhook()
  ```

  ```python Python SDK theme={null}
  from faxplus import ApiClient, WebhooksApi, Webhook
  from faxplus.configuration import Configuration

  webhook = Webhook(target='http://myapp.com/fax_received', event='fax_received')

  conf = Configuration()
  conf.access_token = access_token
  # header_name and header_value required only when using the OAuth2 token scheme
  api_client = ApiClient(header_name='x-fax-clientid', header_value=client_id, configuration=conf)
  api = WebhooksApi(api_client)
  resp = api.create_webhook(body=webhook)
  ```

  ```java Java theme={null}
  /**
   * Example below uses Apache HTTP Client 4 with Fluent API
   **/

  String url = "https://restapi.fax.plus/v3/hooks";

  String jsonBody = ...; // See request body example

  String result = Request
      .Post(url)
       // The x-fax-clientid header is required only when using the OAuth2 token scheme
      .addHeader("x-fax-clientid", "YOUR_CLIENT_ID")
      .addHeader("Content-Type", "'application/json'")
      .addHeader("Accept", "'application/json'")
      .addHeader("Authorization", "'Bearer {access-token}'")
      .bodyString(jsonBody, "application/json")
      .execute()
      .returnContent().asString();

  System.out.println(result.toString());
  ```

  ```go Go theme={null}
  package main

  import (
         "bytes"
         "net/http"
  )

  func main() {

      headers := map[string][]string{
          // The x-fax-clientid header is required only when using the OAuth2 token scheme
          "Content-Type": []string{"application/json"},
          "Accept": []string{"application/json"},
          "Authorization": []string{"Bearer {access-token}"},
          "x-fax-clientid": []string{"YOUR_CLIENT_ID"}
      }

      data := bytes.NewBuffer([]byte{jsonReq})
      req, err := http.NewRequest("POST", "https://restapi.fax.plus/v3/hooks", data)
      req.Header = headers

      client := &http.Client{}
      resp, err := client.Do(req)
      // ...
  }
  ```

  ```php PHP theme={null}
  <?php

  require 'vendor/autoload.php';

  $headers = array(
      'Accept' => 'application/json',
      'Authorization' => 'Bearer {access-token}',
      // The x-fax-clientid header is required only when using the OAuth2 token scheme
      'x-fax-clientid' => '{client ID}',
  );

  $client = new GuzzleHttp\Client();

  // Define array of request body.
  $request_body = ...;  // See request body example

  try {
      $response = $client->request('POST','https://restapi.fax.plus/v3/hooks', array(
          'headers' => $headers,
          'json' => $request_body,
          )
      );
      print_r($response->getBody()->getContents());
   }
   catch (GuzzleHttp\Exception\BadResponseException $e) {
      // handle exception or api errors.
      print_r($e->getMessage());
   }

   // ...
  ```

  ```bash cURL theme={null}
  # You can also use wget
  curl -X POST https://restapi.fax.plus/v3/hooks \
    -H 'Content-Type: application/json'  \
    -H 'Accept: application/json'  \
    -H 'Authorization: Bearer {access-token}' \
    # The x-fax-clientid header is required only when using the OAuth2 token scheme
    -H 'x-fax-clientid: "YOUR CLIENT_ID"'
  ```
</RequestExample>


## OpenAPI

````yaml post /hooks
openapi: 3.0.1
info:
  title: Fax.Plus REST API
  description: >-
    This is the Fax.Plus API v3 developed for third party developers and
    organizations. In order to have a better coding experience with this API,
    let's quickly go through some points:<br /><br /> - This API assumes
    **/accounts** as an entry point with the base url of
    **https://restapi.fax.plus/v3**. <br /><br /> - This API treats all date and
    times sent to it in requests as **UTC**. Also, all dates and times returned
    in responses are in **UTC**<br /><br /> - Once you have an access_token, you
    can easily send a request to the resource server with the base url of
    **https://restapi.fax.plus/v3** to access your permitted resources. As an
    example to get the user's profile info you would send a request to
    **https://restapi.fax.plus/v3/accounts/self** when **Authorization** header
    is set to **Bearer YOUR_ACCESS_TOKEN** and custom header of
    **x-fax-clientid** is set to YOUR_CLIENT_ID
  version: 3.4.0
  contact:
    name: Fax.Plus
    email: info@fax.plus
    url: https://github.com/alohi
servers:
  - url: https://restapi.fax.plus/v3
  - url: /v3
security: []
paths:
  /hooks:
    post:
      tags:
        - Webhooks
      summary: Register new webhook
      description: >-
        Register a new webhook which will be called on a specific event. See the
        WebhookCallback model. (Permitted scopes: **fax:all:edit**,
        **fax:webhook:edit**)
      operationId: createWebhook
      requestBody:
        $ref: '#/components/requestBodies/Webhook'
      responses:
        '200':
          $ref: '#/components/responses/WebhookId'
        '400':
          $ref: '#/components/responses/Error'
        '500':
          $ref: '#/components/responses/ServerError'
      security:
        - oauth2:
            - all
        - personal_access_token:
            - fax:all:edit
            - fax:webhook:edit
components:
  requestBodies:
    Webhook:
      description: Request to create new webhook
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Webhook'
  responses:
    WebhookId:
      description: Webhook ID
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/WebhookId'
    Error:
      description: Error object in case there's a problem with given data
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: invalid_user_id
            description: Invalid user id given
    ServerError:
      description: Error object in case there's a server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: internal_server_error
            description: An unexpected error happened, please contact support
  schemas:
    Webhook:
      description: Webhook model
      type: object
      properties:
        id:
          type: string
          description: Webhook ID
        target:
          type: string
          description: Webhook target URL
        event:
          $ref: '#/components/schemas/WebhookEventType'
        numbers:
          type: array
          nullable: true
          items:
            type: string
            nullable: false
            example: '+12135550123'
            pattern: ^[+][1-9][0-9]{1,14}$
            minLength: 2
            maxLength: 16
          minItems: 1
          description: >-
            A list of phone numbers used to filter webhook triggers. If
            specified, the webhook will only fire for inbound or outbound calls
            involving these numbers. Pass null to disable filtering. An empty
            array is invalid
          example:
            - '+12135550123'
      required:
        - target
        - event
      example:
        target: http://myapp.com/fax_received
        event: fax_received
      additionalProperties: false
    WebhookId:
      description: Webhook ID
      type: object
      properties:
        id:
          type: string
          description: Webhook ID
      required:
        - id
      example:
        id: 6048b47181dbe1a7d67fcc98
      additionalProperties: false
    Error:
      properties:
        description:
          type: string
        error:
          type: string
      additionalProperties: false
    WebhookEventType:
      description: Webhook event type
      enum:
        - fax_received
        - fax_sent
        - fax_page_received
      type: string
  securitySchemes:
    oauth2:
      type: oauth2
      description: OAuth2 Authorization Grant
      flows:
        authorizationCode:
          authorizationUrl: >-
            https://accounts.fax.plus/login?response_type=code&client_id=YOUR_CLIENT_ID&redirect_uri=http://localhost&scope=all
          tokenUrl: https://accounts.fax.plus/token
          refreshUrl: >-
            https://accounts.fax.plus/token?grant_type=refresh_token&refresh_token=YOUR_REFRESH_TOKEN
          scopes:
            all: >-
              for now when a user grants permission, all grants will be
              permitted
    personal_access_token:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Personal Access Token (PAT) is a Bearer token used for secure API calls.
        For direct API calls, the PAT is used in the Authorization header as
        'Bearer {PAT}'. For MCP usage, configure your PAT in your MCP client
        settings (e.g., in your IDE's MCP server configuration) - authentication
        will be handled automatically.

````