Skip to navigation

Webhook Listeners

View as Markdown

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.
  • 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.

MethodPathEndpoint reference
GET/platform/extensions/listenersList webhook listeners
POST/platform/extensions/listenersCreate webhook listener
GET/platform/extensions/listeners/{id}Get webhook listener
PATCH/platform/extensions/listeners/{id}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

FieldTypeRequiredNotes
idstringread-onlyUnique identifier of this configuration, assigned by the server. Send it in update requests to identify the configuration.
display_namestring✅A readable name for the listener. 3 to 64 characters.
url_uuidsarray<string>read-onlyIdentifiers used to build the listener’s public webhook URL. Generated by the server on create and cannot be changed.
signatureFunctionSignatureSettingsThe technical name and description that identify this listener.
reject_processing_dslstringMoveworks 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_enabledbooleanIf true, possibly sensitive data is redacted from this listener’s logs.
securitySecuritySettingsHow the listener endpoint is secured, such as Moveworks authentication and an IP allowlist.
verificationVerificationSettingsRequest-level checks, such as signature verification, run on each incoming request.
payloadPayloadSettingsHow the request payload is parsed, validated and mapped into an event.
debounceDebounceSettingsSettings that collapse a burst of duplicate requests into a single event.
challengeChallengeSettingsSettings for answering one-time verification (CRC) challenge requests from the external system.
updated_timestringread-onlyWhen the configuration was last updated.
updated_bystringread-onlyWho last updated the configuration.
versionVersion✅Document version. On update, send back the num from your last read.

Example create body

{
"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."
}
}