HTTP Trigger

The HTTP Trigger connector lets you create a webhook URL to perform hypertext transfer protocol (HTTP) GET/POST requests. When a request is made to the URL, it starts the automation or agent that uses the trigger.

Note The steps below set up the trigger in an automation. To start an agent with an HTTP request and send it files, refer to the Send Files to an Agent section.

Perform the following steps to configure the HTTP Trigger Connector:

1. Click Configure Trigger from the left navigation panel.
2. Within the Configure Trigger step, click the HTTP connector.
   Click to enlarge
3. Select HTTP Request Trigger. This trigger will be activated whenever you make an HTTP GET/POST request to a specific webhook URL.
   Click to enlarge
4. Select a Method, i.e., GET/POST.
   Click to enlarge
5. Enable the Secure HTTP Trigger to add security to the HTTP trigger. The Secret value is automatically assigned once the setting is enabled. You can also set the Secret as per the criteria. Click Proceed.

   Note When Secure HTTP trigger is enabled, you can only execute URLs with the key secret pair.

   Click to enlarge

6. You will find the applicable input “URL.” This URL will be the webhook URL that you can use to see the automation working. Click Test Trigger.

   Note You can update the configuration of a configured HTTP Trigger with the same URL.
   

   Click to enlarge

   You should be able to see the output as follows:
   

   Click to enlarge

   NoteThe output doesn’t appear because we haven’t tested the Trigger URL yet.

   Next, to try if the trigger is working real-time, perform the following steps:

1. Copy the Input URL that you see above and paste it on a new browser tab.
2. Pass the key and secret pair parameter configured previously to the Input URL, for example, https://trigger_input_URL?ah-http-key=U2>ggyhbsogvlps and hit enter. You should see an output similar to the following:
   {"result": "The rule is currently being tested or not activated","trigger_id":"1111ab1c1ab11111ca11b111111ca1bc"}
3. Return to your Test Trigger setup page and click Test Trigger again. In the output, you will see your query parameter as follows:
   query: ah-http-key:"U2>ggyhbsogvlps"
   Here’s what you see:
   Click to enlarge

   Note You can also test the trigger in HTTP client by passing the key: secret pair in the Header section.

4. Lastly, you can either pass a new query parameter and Retest the trigger or hit Save and Continue (see screenshot in step 3).

Note After successfully configuring a trigger, if you re-configure any other trigger you will be prompted to revert to the previously configured trigger. You can revert back to the last trigger configurations by clicking the Revert Changes button.

This completes your step of configuring your HTTP trigger.

You can send files and images to an agent in the same HTTP request that starts it. The agent reads documents, understands images, and can pass a file on to its tools, for example to upload an image to your stack with Create an Asset.

Only the agent's HTTP trigger accepts files. If you don't send files, the trigger works exactly as before.

Other file types are rejected, including audio, video, GIF and ZIP files.

Limits:

• Up to 3 files per request.
• Up to 5 MB per file.

1. Copy your agent's trigger URL. In Agent Builder, click the HTTP trigger; the URL is shown under URL.
2. Send a POST request to the URL with a multipart/form-data body.
3. Put each file in a field named files. To send more than one file, repeat the files field.
4. Optionally, add these text fields:
   • prompt: what you want the agent to do with the files. Without a prompt, the agent works from its own instructions and the files.
   • runInputs: the agent's run inputs, as a JSON object in text form, for example {"locale":"en-us"}.

File types are detected for you. Some tools, such as curl, send many files with a generic type (application/octet-stream). In that case the file extension is used, so name your files with the right extension.

If your trigger is secured with an API key, send the key the same way you do today: as a header or a query parameter, using the key name and value set on the trigger.

The trigger responds right away with the run's ID and the status processing. The agent doesn't return files in the HTTP response; check the result in the agent's execution log.

Example: curl

curl -X POST "<your-trigger-url>" \
  -H "<auth-key-name>: <auth-key-value>" \
  -F "prompt=Create a product entry from the attached spec and photo" \
  -F "[email protected]" \
  -F "[email protected]"

Leave out the -H line if your trigger isn't secured with an API key.

Example: Postman

1. Set the method to POST and paste your trigger URL.
2. Open Body and select form-data.
3. Add a row with the key files, change its type from Text to File, and choose your file.
4. Add another files row for each extra file.
5. Optionally, add a prompt row (type Text) with your instructions.
6. If your trigger is secured, add the key under Headers or Params.

Note Use POST. If you send a file with a GET request, the file is ignored and the agent runs without it.

• PDF, Word (.docx), CSV and text files: the agent gets the file's text up front. For a long file, it gets the beginning up front and can read the rest when it needs to.
• PowerPoint, Excel and older Word (.doc) files: the text isn't read up front. The agent gets the file and opens it when it needs to.
• Images: the agent gets a description of what's in the image, including any text it can read in it.
• Using files in tools: each file comes with a link the agent can pass to its tools. For example, the agent can upload an attached image to your stack with Create an Asset.

Open the run in the agent's execution log. The run's Input lists each file under attachments, with its name, size and type. File contents are not stored in the log.

Click to enlarge

When a request is rejected, the agent doesn't run and no AI credits are used.

These errors return a body that names the file and the rule:

{
  "success": false,
  "error": "FILE_REJECTED",
  "message": "product-spec.pdf: File exceeds maximum size of 5MB",
  "file": "product-spec.pdf",
  "rule": "file_too_large"
}

file is empty when the rule applies to the whole request, such as too_many_files.

Other errors you might see:

• Only the HTTP trigger takes files. Scheduled and event triggers have no caller to send a file.
• Files are input only. The agent doesn't return files in the HTTP response. To have the agent create a file, refer to Files by Agent OS.
• Existing calls keep working. JSON, text and form requests without files, and image links in the request body, behave as before.