> ## Documentation Index > Fetch the complete documentation index at: https://docs.commenda.io/llms.txt > Use this file to discover all available pages before exploring further. # Create webhook > Register your webhook with Commenda. ## OpenAPI ````yaml POST /webhooks openapi: 3.0.1 info: title: Commenda Public APIs description: >- APIs for Commenda entity management, partner incorporation, indirect tax, compliance, and corporate operations. license: name: NONE url: NONE version: 1.0.0 servers: - url: https://api.prod.commenda.io/api/v1 description: Commenda platform APIs, including Partner Incorporation and Commenda OS. - url: https://transaction-tax.api.in.commenda.io/api/v1 description: Global Indirect Tax API. security: - bearerAuth: [] paths: /webhooks: post: summary: Create a new webhook. description: Register your webhook with Commenda. operationId: registerWebhook requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateWebhookRequest' responses: '200': description: Sales tax registration response content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/CreateWebhookResponse' message: type: string example: Successfully registered webhook. '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: CreateWebhookRequest: type: object required: - api_version - url - key - status - topics properties: api_version: type: string description: >- The version of the API for which you registered the webhook. This helps to maintain backward compatibility. If in newer versions the event payload is changed, your webhook will keep receiving the payload from this api version. This will be 'v1.0' for now and we will come up with more versions and a changelog later. name: type: string description: Optional name to define the purpose of the webhook. topics: type: array items: type: string enum: - REGISTRATIONS.EXISTING.VALIDATION_FAILED - REGISTRATIONS.EXISTING.VALIDATION_SUCCEEDED description: >- An array of topics to listen to. When any of these topics are triggered, the webhook will be pinged. url: type: string description: >- Your webhook url that will be hit once an event happens. Only HTTPS urls are allowed. key: type: string description: >- Secure string provided by the user. It will be used during HMCA process to keep the event payloads secure. Make sure to keep it safe as you will need it during validating event payloads. This key won't be returned back by any other endpoint. status: type: string enum: - ENABLED - DISABLED description: >- If the webhook is active or not. If a webhook is disabled it won't be called when a topic is triggered. CreateWebhookResponse: type: object properties: id: type: string description: >- The unique identifier for this webhook. You will need this if you need to update or delete this webhook. example: 2535af08-a139-4d0c-9827-1651e46dfbcf api_version: type: string description: >- The version of the API for which you registered the webhook. This will be 'v1.0' for now. This helps to maintain backward compatibility. If in newer versions the event payload is changed, your webhook will keep receiving the payload from the original api version. example: v1.0 name: type: string description: Optional name to define the purpose of the webhook. example: handle_existing_registrations_validation_failure topics: type: array items: type: string enum: - REGISTRATIONS.EXISTING.VALIDATION_FAILED - REGISTRATIONS.EXISTING.VALIDATION_SUCCEEDED description: >- An array of topics to listen to. When any of these topics are triggered, the webhook will be pinged. url: type: string description: >- Your webhook url that will be hit once a topic is triggered. Only https:// urls will work. example: https://bruno-simon.com/ key: type: string description: >- Use for signing the event payloads. All the event payloads will be signed using this key. Make sure to keep it safe as you will need it during validating event payloads. example: couabowugowubfvow2efgofqpifhdiubvafobafou2ee status: type: string enum: - ENABLED - DISABLED description: >- If the webhook is active or not. If a webhook id disabled it won't be called when a topic is triggered. created_at: type: number description: Timestamp in UTC when this webhook was created. example: 1727284490 Error: type: object required: - error properties: error: type: object properties: type: type: string description: 'Specific Error type. Example: CLIENT_INVALID_REQUEST_BODY.' example: CLIENT_INVALID_REQUEST_BODY doc_url: type: string description: >- A link to the docs with details about this error. Example: https://sales-tax-docs.commenda.io/ example: https://sales-tax-docs.commenda.io/ title: type: string description: >- A short title describing the error. Example: Missing query parameters. example: Failed to validate the request body detail: type: string description: >- A json string with a description on how to fix the error. Example {"description":"Please pass in a valid corporation_id"} status: type: number description: >- The status code. It should be the same as the HTTP protocol status code. Example: 200 example: 400 instance: type: string description: >- The relative path that was hit by the user. Example: /api/v1/corporations/1 Errors: type: array items: type: object properties: details: type: string description: More details on how to solve this particular error. pointer: type: string description: >- Relative reference to missing or invalid piece of passed information. securitySchemes: bearerAuth: type: http scheme: bearer ````