Your first webhook automation

Who this is for: people who want a workflow to react to events in another system, for example a new ticket in a web shop.

Before you start: you need your AI assistant connected, the Manage webhooks permission, and a colleague who can approve workflows (the Approve workflows permission). A person approves each version, and it can’t be the one who made it.

In this tutorial you build a workflow that works like this: when the web shop sends a new support ticket, Liitora checks that it has a subject and an email address, then creates the ticket in your service desk. It takes about 20 minutes.

1. Ask your AI assistant

Write to your assistant, in your own words:

When our web shop sends a new support ticket to a Liitora webhook, check that it has a subject and an email, then create the ticket in our service desk at https://servicedesk.example.com with POST /api/tickets. Call the webhook new-tickets.

The assistant searches the library, then calls create_webhook_workflow. That creates:

• the webhook endpoint new-tickets, with its URL and signing steps;
• a draft workflow with its steps and tests;
• a checklist of what is still missing, with links for you.

The workflow looks like this:

name: Forward new tickets to the service desk
description: When the web shop sends a new support ticket, check that it has a subject and an email, then create it in the service desk.
on:
  webhook: { endpoint: new-tickets }
steps:
  - id: check
    name: Check that the ticket has a subject and an email
    uses: platform/evaluate@v1
    with:
      expression: "${{ trigger.body.subject != null && trigger.body.email != null }}"
      fail_if_false: true
      message: The ticket needs a subject and an email address.
  - id: forward
    name: Create the ticket in the service desk
    uses: platform/http.request@v1
    connections: { api: service-desk }
    with:
      method: POST
      url: /api/tickets
      json:
        title: "${{ trigger.body.subject }}"
        requester: "${{ trigger.body.email }}"
        source: web-shop

trigger.body is the body the web shop sends. The second step uses the connection service-desk, so the workflow never contains the service desk’s address or key.

You can also create the endpoint yourself first on the Webhooks page (Add an endpoint) and tell the assistant its name. See Set up a webhook.

2. Add the connection and the key

The service desk needs an API key. The assistant creates the connection service-desk and asks for the key with request_secret. It shows you a link.

1. Open the link. You see what is needed and why.
2. Paste the API key and save. The page says Saved. Go back to your chat.

The key goes straight to Liitora, encrypted. It never passes through the chat. See Add a secret.

Activation runs the workflow in production, so the connection needs a Production setup. Check it on the Connections page. See Create a connection.

3. Check the tests

Open the link Review workflow that the assistant shows, and select the Tests tab. A webhook workflow needs at least these test cases, and they must all pass:

Test case	What it proves
Creates the ticket in the service desk (happy path)	A ticket with a subject and an email is sent to the service desk exactly once.
Fails cleanly when the service desk is down (upstream failure)	When the service desk answers 503, the run fails at the forward step.
Refuses a ticket without an email (malformed payload)	A body without an email fails the check, and nothing is sent.

Each check is written as a sentence, such as “Calls POST /api/tickets exactly once”. Tests use made-up data and never reach the network. If a required kind is missing, the tab lists it under Some required test cases are missing, and you can ask the assistant to add it. See Read and write workflow tests.

4. Approve and activate

The assistant cannot turn the workflow on. It shows an Approve & activate link instead.

1. Send the link to your colleague, or open it yourself if you did not make this version. Versions made by the assistant through your API token count as yours.
2. On the page, read What it does, What changed and What the tests check.
3. Select Approve this version, then Activate.

The workflow is now Active. The endpoint page lists it under Workflows it starts. See Approve a workflow.

5. Send a test delivery

1. Open Webhooks and select new-tickets.
2. A person with the Reveal secrets permission selects Show secret and copies it.
3. In a terminal, set the secret and send a signed ticket. This uses the bash sample from Webhook signing with a ticket body:

export LIITORA_WEBHOOK_URL='<the URL from the endpoint page>'
export LIITORA_WEBHOOK_SECRET='<the signing secret>'
body='{"subject":"Printer is offline","email":"user@example.com"}'
ts="$(date +%s)"
sig="$(printf '%s.%s' "$ts" "$body" | openssl dgst -sha256 -hmac "$LIITORA_WEBHOOK_SECRET" -hex | sed 's/^.* //')"
curl -sS -X POST "$LIITORA_WEBHOOK_URL" \
  -H 'Content-Type: application/json' \
  -H "X-Liitora-Timestamp: $ts" \
  -H "X-Liitora-Signature: sha256=$sig" \
  -H "Idempotency-Key: ticket-test-$ts" \
  --data-binary "$body"

4. The answer lists the run it started: {"duplicate":false,"event_id":"...","run_ids":["..."]}.

The ready-made script under Send a test delivery sends a sample body without a subject or email. With this workflow, that run fails at the check step, which is what the malformed payload test expects.

6. Watch the run

1. Open Runs. The newest run is at the top, Started by Webhook.
2. Open it. Each step shows its status. Expand Create the ticket in the service desk to see the input, the output and the HTTP calls, with the status your service desk answered.
3. If a step failed, its error ends with a code. Look it up in Error codes, fix the cause and select Retry from this step. See Read run logs.

Now give the web shop the URL and the secret, and set it up to sign each request the same way.

Next steps

• Webhook signing
• Rotate webhook secrets
• Common failures