Webhooks

When using Lago, the app generates several events that you can listen to in order to trigger workflows. Each time an event is generated, you can view it in the Lago application using the webhook logs. This allows you to take a closer look at the generated events, detect possible errors, and retry them.

​

Adding a webhook URL

To add a webhook endpoint via the Lago app, follow these steps:

1. Go to the Developers section via the sidebar;
2. Open the Webhooks tab;
3. Click Add a webhook;
4. Enter the webhook URL;
5. Choose the webhook signature between JWT and HMAC; and
6. Click Add webhook to confirm.

​

The webhook signature

By creating a webhook endpoint, you have two signature options.

• Dashboard
• API

• The first is JWT, with a possibly lengthy payload header and potential size limits;
• The second is HMAC, which features a shorter payload header and no size restrictions.

Webhook endpoint signature

• The first is JWT, with a possibly lengthy payload header and potential size limits;
• The second is HMAC, which features a shorter payload header and no size restrictions.

Webhook endpoint signature

Choosing the webhook signature

Copy

Ask AI

LAGO_URL="https://api.getlago.com"
API_KEY="__YOUR_API_KEY__"

curl --location --request POST "$LAGO_URL/api/v1/webhook_endpoints" \
  --header "Authorization: Bearer $API_KEY" \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "webhook_endpoint": {
      "webhook_url": "https://foo.bar",
      "signature_algo": "hmac"
    }
  }'

​

Locate your HMAC signature token

To find your HMAC signature token, navigate to Developers > Webhooks and locate the HMAC Signature Token. Then, reveal and copy the key.

Locate your HMAC siganture token

​

Accessing the webhook logs

Once a webhook is registered in the app, you can access the webhook logs:

1. Go to the Developers section via the sidebar;
2. Open the Webhooks tab;
3. Click on the webhook endpoint to see the list of events; and
4. Click the reload icon to see new events (optional).

Webhook logs

​

Accessing a specific event

You can see the details of a specific event by clicking on it. Depending on the event status, you will have access to two or three main blocks:

1. A list of properties, including:
   1. Timestamp: the timestamp of the event;
   2. Webhook URL: the URL used to listen to events;
   3. Unique key: idempotency key associated with the event;
   4. Webhook type: the webhook type used to understand the action triggered;
   5. Response: the response code (i.e. acknowledgement of receipt);
   6. Number of retries: if the event failed, the number of retries attempted;
2. A JSON snippet with the arguments sent by Lago; and
3. If the event failed, an error response will be included.

​

Errors and retries

Your webhook server should response with a 2xx (200, 201, 202, 204) status code to acknowledge the receipt of the event. If the response is not supported as a success, Lago will consider it as failed. Some events generated by Lago may not be received on the user side, which is why Lago displays an error status in the user interface.