To begin sending webhooks to your listener, some external systems require an initial setup validation known as a verification challenge. This one-time process confirms that your endpoint is correctly configured to receive webhooks, preventing misrouting or unauthorized registrations.
Verification challenges are not mandatory for all systems. Many, like payment processors or code repositories, rely solely on signature verification. However, platforms such as messaging services often mandate challenges to establish trust. For instance, Slack uses a challenge token, while Adobe employs a header code response. This step enhances security by ensuring only legitimate endpoints are registered, protecting against spoofed webhook URLs. Our platform supports this through a declarative UI, allowing you to define rules and responses without custom coding, accommodating a variety of external system requirements.
Webhook verification challenges involve a one-time setup validation where an external system sends a special request to your endpoint to verify its readiness. This process typically follows a challenge-response pattern, ensuring your server, in this case Agent Studio, can correctly respond with expected data or status codes.
The external system initiates a verification request, often distinguishable by unique parameters or headers. Your endpoint must detect this request and respond appropriately, signaling that it is the intended recipient. This might involve returning a specific status code, header value, a challenge token, or a computed value based on the request data.
Challenges prevent unauthorized endpoint registration by requiring active participation. They also mitigate risks of misconfiguration, ensuring your server can handle webhook traffic before full integration. However, improper setup (e.g., incorrect token hashing) can lead to failed verifications, so alignment with the external system’s documentation is critical.
Our UI simplifies setup for webhook listeners, providing a dedicated One Time Verification Challenge panel when configuring your Listener. To begin, create or edit a listener for incoming events:
Set Challenge Detection: Use Moveworks DSL to define rules for detecting verification requests. This field accesses five elements:
raw_body: The unparsed HTTP body as bytes (e.g., b'{{"event":"update"}}').
parsed_body: The JSON-parsed raw body.
query_params: URL query parameters destructured as JSON.
headers: The headers of the request.
method: The method of the request. For example, a rule such as method == "POST" allows only POST requests
HTTP Response Status Code: Select a status code to return in the response, aligning with the external system’s requirement. The default is 200 OK, but options like 204 No Content may apply. Choose based on the system’s documentation.
HTTP Response Headers: Use Moveworks Data Mappers to define custom headers for the response. This field supports dynamic values based on request data, enhancing flexibility for specific system needs.
HTTP Response Body: Configure the response body using Moveworks Data Mappers. This can include static text or dynamic values, such as a challenge token.
Add Challenge Token: Click this button to create a challenge token for systems requiring a signed response. Each token has four fields:
example_name) to reference the token later with the syntax challenge_token["name"].HMAC-SHA256) used by the external system.query_params["challenge"]) using Moveworks Data Mappers.The platform hashes the payload with the secret and algorithm, making the result available in the response body via challenge_token["name"] syntax.
The following diagram visually represents both one-time verification flows. Color coding: