Skip to main content
Go to the Studio
Robot settings

Webhook

Webhook

A webhook starts a robot with an API call, which is how Roberty connects to other systems, platforms and scripts. It is the usual way to wire Roberty to an ERP, a CRM, a web form, or anything else that can make an HTTP request.

How it works​

Each robot can have its own secret webhook token. When another system sends a request to Roberty's API carrying that token, the robot starts immediately. You can pass data to the robot in the request and, if you want, get a custom response back.

Generating the webhook token​

  1. Open the robot's Designer.
  2. Click the gear icon (⚙️) to open the settings.
  3. Find the Webhook token section.
  4. Click the generate-token icon.
  5. Confirm when asked.
  6. Copy the token.
Keep the token secret

The webhook token grants the power to start the robot remotely. Do not share it with anyone outside the robot's development. If it is ever compromised, generate a new one to invalidate the old.

Starting the robot with POST​

Send a POST request to the endpoint below, with the token in the header and the arguments in the body.

Endpoint:

POST https://api.roberty.app/main/public/webhook/request

Required header:

x-roberty-token: <your-token-here>

Request body (JSON):

json
{
  "nome": "Roberty",
  "documento": "123.456.789-00"
}

The values in the body reach the robot as arguments, available through expression fields or custom code.

Starting the robot with GET​

You can also start the robot with a GET request, passing the arguments in the URL.

Example:

GET https://api.roberty.app/main/public/webhook/request?nome=Roberty&documento=123.456.789-00

The x-roberty-token header is still required on a GET.

Following the run​

The response to the trigger request carries an identifier called webhookCallId. Use it to check the run's status and result:

Query endpoint:

GET https://api.roberty.app/prod/1/customer/robot/webhookResponse/{webhookCallId}

The statuses you can get back:

StatusWhat it means
WAITINGThe robot is still running and has not returned a response.
DONEThe run finished with a custom response.

Returning a custom response​

For the robot to send data back to whatever started it, add the Respond to webhook action to the flow. It returns an object with whatever you want in it.

Example response:

json
{
  "response": { "status": "processed", "codigo": "NF-00123" },
  "status": "DONE"
}

Without that action, querying the webhookCallId returns WAITING for as long as the robot runs.

Next​