> This page is for API Reference & Tools.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.moveworks.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.moveworks.com/_mcp/server.

# Webhook Listeners

> Create, read and update webhook listeners through the Moveworks Configuration API.

`platform.extensions.listeners`

A webhook listener receives events from an external system at a Moveworks URL, checks them, and passes the payload to the system plugins subscribed to it.

* **Endpoint:** `/platform/extensions/listeners`  |  **Methods:** GET, PATCH, POST
* **Request shape:** fields go at the top level of the JSON body, with no `resource` wrapper. The item's `id` goes in the URL for reads and updates, not in the body.
* **Updates:** a JSON merge-patch with `version: {num, change_description}` from your last read. Lists of objects merge row by row, so read first and send the whole list when you remove or reorder rows. See [Tool Studio](/api-reference/configuration-api/tool-studio/overview#how-updates-work).
* **References:** System plugins subscribe to a listener with its `id` in `triggering_config.system_triggering_config.event_subscriptions[].listener_id`.

### Endpoints

All paths are relative to `https://api.moveworks.ai/configurations/v1alpha1`. Each endpoint page lists the request and response schema, an example, and the errors it can return.

| Method  | Path                                  | Endpoint reference                                                                                                |
| ------- | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `GET`   | `/platform/extensions/listeners`      | [List webhook listeners](/api-reference/configuration-api/tool-studio/webhook-listeners/list-webhook-listeners)   |
| `POST`  | `/platform/extensions/listeners`      | [Create webhook listener](/api-reference/configuration-api/tool-studio/webhook-listeners/create-webhook-listener) |
| `GET`   | `/platform/extensions/listeners/{id}` | [Get webhook listener](/api-reference/configuration-api/tool-studio/webhook-listeners/get-webhook-listener)       |
| `PATCH` | `/platform/extensions/listeners/{id}` | [Update webhook listener](/api-reference/configuration-api/tool-studio/webhook-listeners/update-webhook-listener) |

### Rules the API checks

* `display_name` is required.
* Up to 5 entries in `verification.validations`.
* `debounce.window_seconds` is one of 0, 30, 60, 180, 300, 600, 900, 1800, 2700 or 3600.
* The server generates `url_uuids`, which make up the listener's public URL. You can't change them through the API.
* `signature_verification.secret_token` comes back redacted.

### Fields

| Field                   | Type                      | Required  | Notes                                                                                                                                             |
| ----------------------- | ------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                    | string                    | read-only | Unique identifier of this configuration, assigned by the server. Send it in update requests to identify the configuration.                        |
| `display_name`          | string                    | ✅         | A readable name for the listener. 3 to 64 characters.                                                                                             |
| `url_uuids`             | array\<string>            | read-only | Identifiers used to build the listener's public webhook URL. Generated by the server on create and cannot be changed.                             |
| `signature`             | FunctionSignatureSettings |           | The technical name and description that identify this listener.                                                                                   |
| `reject_processing_dsl` | string                    |           | Moveworks DSL rule that acts as a kill switch. When true, the request is not processed. Evaluated against request_body, headers and query_params. |
| `log_redaction_enabled` | boolean                   |           | If true, possibly sensitive data is redacted from this listener's logs.                                                                           |
| `security`              | SecuritySettings          |           | How the listener endpoint is secured, such as Moveworks authentication and an IP allowlist.                                                       |
| `verification`          | VerificationSettings      |           | Request-level checks, such as signature verification, run on each incoming request.                                                               |
| `payload`               | PayloadSettings           |           | How the request payload is parsed, validated and mapped into an event.                                                                            |
| `debounce`              | DebounceSettings          |           | Settings that collapse a burst of duplicate requests into a single event.                                                                         |
| `challenge`             | ChallengeSettings         |           | Settings for answering one-time verification (CRC) challenge requests from the external system.                                                   |
| `updated_time`          | string                    | read-only | When the configuration was last updated.                                                                                                          |
| `updated_by`            | string                    | read-only | Who last updated the configuration.                                                                                                               |
| `version`               | Version                   | ✅         | Document version. On update, send back the num from your last read.                                                                               |

### Example create body

```json
{
  "display_name": "Ticket closed events",
  "signature": {
    "name": "ticket_closed",
    "display_name": "Ticket Closed",
    "description": "Emitted by the ticketing system when a ticket is closed.",
    "arguments": [
      {
        "name": "ticket_id",
        "description": "The closed ticket's id.",
        "type": {
          "primitive": "string"
        },
        "required": true
      }
    ]
  },
  "verification": {
    "validations": [
      {
        "signature_verification": {
          "secret_token": "shared-secret-from-the-ticketing-system",
          "signing_algorithm": "HS256",
          "signature_payload_bender": {
            "payload": "request_body"
          },
          "received_signature_bender": {
            "signature": "headers.x-signature"
          }
        }
      }
    ]
  },
  "payload": {
    "mapper_bender": {
      "ticket_id": "request_body.ticket_id"
    }
  },
  "debounce": {
    "key_paths": [
      "ticket_id"
    ],
    "window_seconds": 60
  },
  "log_redaction_enabled": true,
  "version": {
    "change_description": "Initial version."
  }
}
```