# Add webhook

Add a webhook

# OpenAPI definition

````json
{
  "openapi": "3.1.1",
  "servers": [
    {
      "url": "https://api.cm.com/sign/v1"
    },
    {
      "url": "https://api.cm.com/sign-sandbox/v1"
    }
  ],
  "security": [
    {
      "JWT": []
    }
  ],
  "info": {
    "version": "1",
    "title": "Sign API",
    "description": "Sign by CM.com offers the ability to have end users sign PDF documents online.\n\nBefore you can start using the API, you need to be provided with credentials. You will have received these credentials, consisting of a Key and a Key Id, when you registered for Sign. If you have not yet received any credentials, you can request them via [this link](https://www.cm.com/app/verification-registration/sign). This will grant you access to the sandbox environment.\n\n*The credentials provided by CM.com are confidential and should be kept secret.*\n"
  },
  "tags": [
    {
      "name": "Webhook",
      "description": "Manage webhooks"
    }
  ],
  "paths": {
    "/clients/{kid}/webhooks": {
      "parameters": [
        {
          "$ref": "#/components/parameters/KeyId"
        }
      ],
      "post": {
        "operationId": "create_client_webhook",
        "summary": "Add webhook",
        "description": "Add a webhook",
        "tags": [
          "Webhook"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Webhook"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Webhook"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      }
    }
  },
  "components": {
    "responses": {
      "Unauthorized": {
        "description": "Unauthorized",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "Forbidden": {
        "description": "Access to the specified resource was denied",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      }
    },
    "parameters": {
      "KeyId": {
        "name": "kid",
        "in": "path",
        "schema": {
          "type": "string",
          "format": "uuid"
        },
        "required": true,
        "description": "a uuid string that identifies the client\n",
        "example": "1d1c8b3f-d33f-412c-8a57-e259d3bc5e05"
      }
    },
    "schemas": {
      "ErrorResponse": {
        "title": "Error Response",
        "type": "object",
        "properties": {
          "status": {
            "type": "integer",
            "format": "int32",
            "description": "Response status code, should match HTTP error code"
          },
          "message": {
            "type": "string",
            "description": "High level description of the error that occurred. This description, when present, can be shown to the end user. It might describe that the system is not available, or that an unexpected error occurred. In test mode, the API will return more information (targeted at the developer) here than in production mode."
          }
        }
      },
      "WebhookUpdate": {
        "type": "object",
        "properties": {
          "url": {
            "type": "string",
            "format": "url",
            "description": "The URL must begin with https://",
            "examples": [
              "https://example.com"
            ]
          },
          "events": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/WebhookType"
            },
            "description": "The subscribed webhook events"
          },
          "headers": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "examples": [
              {
                "My-Custom-Header": "Example"
              }
            ],
            "description": "The request HTTP headers"
          },
          "disabled": {
            "type": "boolean",
            "description": "Provide with value false to re-enable automatically disabled webhooks.",
            "examples": [
              false
            ]
          }
        }
      },
      "Webhook": {
        "title": "Webhook",
        "allOf": [
          {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid",
                "description": "a uuid string that identifies the webhook",
                "examples": [
                  "eab04267-d849-46d1-9fe3-e7ff0b2c55cf"
                ],
                "readOnly": true
              }
            }
          },
          {
            "$ref": "#/components/schemas/WebhookUpdate"
          },
          {
            "type": "object",
            "properties": {
              "disabled": {
                "type": "boolean",
                "description": "Webhooks may automatically be disabled if too many requests fail",
                "readOnly": true
              },
              "createdAt": {
                "type": "string",
                "format": "date-time",
                "description": "The date the invite was created",
                "readOnly": true
              },
              "updatedAt": {
                "type": "string",
                "format": "date-time",
                "description": "The date the invite was created",
                "readOnly": true
              }
            },
            "required": [
              "url"
            ]
          }
        ]
      },
      "WebhookType": {
        "type": "string",
        "description": "Webhook event types that can be subscribed to. By default, dossier.state.updated, dossier.prepared, and dossier.invite.undelivered events are sent.\n",
        "enum": [
          "dossier.invite.created",
          "dossier.invite.expired",
          "dossier.invite.undelivered",
          "dossier.invite.viewed",
          "dossier.invitee.state.updated",
          "dossier.prepared",
          "dossier.state.updated",
          "dossier.invitee.reassignRequest.state.updated"
        ]
      }
    },
    "securitySchemes": {
      "JWT": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "In order to authenticate you need to use your credentials to generate a JWT Bearer token. The [JWT token](https://jwt.io/introduction/) has to be generated using the `HS256` algorithm and your credentials. This JWT has to contain the following attributes: `iat`, `nbf`, `exp`  in the payload, as well as the attribute `kid` in the header of the JWT. This `kid` attribute needs to contain the Key Id of your credentials.\n\nThe generated token needs to be passed via the HTTP Authorization header like:\n\n```\nAuthorization: Bearer GENERATED_TOKEN_HERE\n```\n\nThere are many libraries available for different programming languages that can help you to generate a JWT. See the Libraries tab on [https://jwt.io](https://jwt.io)\n"
      }
    }
  },
  "x-readme": {
    "explorer-enabled": true,
    "proxy-enabled": true
  },
  "_id": {
    "buffer": {
      "0": 106,
      "1": 177,
      "2": 26,
      "3": 196,
      "4": 252,
      "5": 46,
      "6": 219,
      "7": 163,
      "8": 234,
      "9": 51,
      "10": 132,
      "11": 96
    }
  }
}
````