There are numerous ways to trigger bot executions from outside of the platform. This document covers how to create and set up triggers for your bot.

​
Webhooks

Webhook triggers let you invoke your bot from any external platform by calling a simple API endpoint. To set up a webhook trigger, follow these steps:

  1. Open the bot that you want to trigger.
  2. Go to the bot Settings tab.
  3. Go to the Bot Triggers section.
  4. Click Add Trigger. Give it any name and choose the webhook trigger type.
  5. Click Create.

You can create as many triggers as you want. Each trigger will have a unique URL that you can use to invoke your bot and a unique key.

Security

Anyone who has access to your trigger URL and key can trigger your bot - both using up your credits and potentially getting access to any data that your bot has access to. Make sure to keep your trigger URL and key safe.

​
Invoking Bot via Trigger

Once your webhook trigger is created, click View on that trigger. You’ll see the URL and key that you can use to invoke your bot. You can trigger your bot by making a POST request to that URL. Pass the key as a header named X-Key. Pass any data that you want to send to your bot as a JSON body.

Here’s an example of how you can trigger your bot using the curl command:

curl https://www.lilbots.io/api/webhooks/TRIGGER_ID/trigger \
 -X POST \
-H "Content-type: application/json; charset=UTF-8" \
-H "x-key: TRIGGER_KEY" \
-d "{\"INPUT\":\"VALUE\"}"

Note that invoking the bot via a trigger is asynchronous. This means that the API call will return immediately and the bot will be executed in the background. You can see the bot execution in the UI via the history tab, or you can use the following method to synchronously wait for the bot to finish executing.

​
Synchronously Waiting for Bot Execution

After executing your bot, you may sometimes want to wait until it is finished running and get back its outputs. This can be easily done by using the sync endpoint:

GET https://www.lilbots.io/api/webhooks/TRIGGER_ID/trigger/invocation/INVOCATION_ID/sync
  • TRIGGER_ID - The ID of your trigger. Same as what you used to trigger the bot.
  • INVOCATION_ID - The ID of the bot invocation. You can get this from the response of the trigger API call. (response.body.invocation.id)
  • Also pass the header X-Key with the trigger key. (same as when triggering the bot)

Sync Timeouts

The sync timeout will wait until your bot has finished executing, but if it takes longer than 5 minutes, it may time out and return a 408 status code. If your bot takes longer than 5 minutes, there are two techniques you can use to get around this:

  1. Implement a retry mechanism that will call the /sync endpoint again if it times out.
  2. If your bot always takes longer than 5 minutes, you may want to wait some time before calling the /sync endpoint to give the bot time to finish executing.

​
Complete API Reference

For a complete reference of the Webhook Triggers API, including authentication, request formats, response structures, and examples, please see our API Reference documentation.