# Integrations

> Under Integrations you connect Echo with your own systems.

Under **Integrations** you connect Echo with your own systems: with an API token your webshop or CRM can add and update subscribers, and webhooks tell your systems right away when something happens in Echo.

## The Integrations page

Open **Integrations** in the left menu. The page has two cards: **API** and **Webhooks**. Click **Use** on a card to open it.

![The Integrations page with the API and Webhooks cards](https://docs.uptools.io/_astro/07-integrations-overview.B5wQAMPg_Zl93qL.webp)

> **Good to know**
>
> - Users with the Administrator or Manager role can create tokens and webhooks. Other roles see the lists at most, or the page tells them they don't have permission.
> - The technical details (requests, responses, signature checks) are in the [developer guide](https://docs.uptools.io/echo/developer-guide/). This chapter covers what you do in the app.

## How to create an API token

An API token is a key your own system uses to reach your Echo account. Create a separate token for each system, so you can revoke one without touching the others.

1. Open **Integrations**, then click **Use** on the **API** card.
2. Click **Generate new token**.

   ![The API page with the Generate new token button](https://docs.uptools.io/_astro/07-integrations-api.D6QmdyzQ_2q42D4.webp)

3. In **Token name**, enter what the token is for, for example the name of your webshop.
4. Under **Access**, choose **Read only** or **Full access**.
5. If the system calling Echo always uses the same IP address, enter it in **Allowed IP addresses**, one address or range per line. Leave it empty to allow any address.
6. Click **Generate token**.

   ![The Generate new token window, filled in](https://docs.uptools.io/_astro/07-integrations-token-new.uSXq_ejl_sKpIT.webp)

7. Copy the token with **Copy** and paste it into your system's settings, then click **Done**.

   ![Your new API token, shown only once](https://docs.uptools.io/_astro/07-integrations-token-created.B_TTqBxn_Z2t6Jnm.webp)

| Access | What the token can do |
|---|---|
| **Read only** | Reads subscribers, groups, segments, fields, campaigns, automations and webhooks. |
| **Full access** | Also adds, changes and deletes them. |

> **Good to know**
>
> - Echo shows the token only once. If you lose it, create a new one and revoke the old one.
> - A token acts with its creator's current role: it can't do more than the person who created it. If the creator leaves the workspace, the token stops working and the list marks it **Inactive**.
> - A workspace can have at most 50 active tokens, and each token at most 20 IP addresses or ranges.
> - Each token can send 120 requests a minute, and 5 imports a minute.

## How to edit or revoke an API token

1. Open the **API** page under **Integrations**.
2. In the **API tokens** list, find the token. The list shows its start, its **Access**, the allowed **IP addresses**, when it was **Last used** and who created it.
3. To change its name or IP addresses, click **Edit**, change them and click **Save changes**. The access can't be changed: for different access, create a new token.
4. To revoke it, click **Revoke**, then click **Revoke** again in the confirmation window.

![The Revoke confirmation window](https://docs.uptools.io/_astro/07-integrations-token-revoke.BmkiPBq6_Z20JC06.webp)

Requests with a revoked token stop working at once. Revoking can't be undone.

## How to find the details your developer needs

The **Documentation** box on the **API** page has everything a developer needs to start:

- **Base URL**: the address the requests go to. Copy it with **Copy**.
- **Headers**: the headers every request needs.
- **Rate limit**: how many requests a token can send in a minute.
- **OpenAPI document**: the full technical reference as a downloadable file.

Below the token list, the **Group IDs** box lists the ID of every group. The API asks for these IDs when a subscriber should join a group. Find a group with **Search groups**, then copy its ID with **Copy**.

![The Group IDs box](https://docs.uptools.io/_astro/07-integrations-group-ids.Cwno3b6l_Z1hyaz.webp)

## How to set up a webhook

A webhook sends a message (an HTTP POST request) to an address you give whenever the events you chose happen, for example when someone subscribes or unsubscribes.

1. Open **Integrations**, then click **Use** on the **Webhooks** card.
2. Click **Create webhook**.

   ![The Webhooks page](https://docs.uptools.io/_astro/07-integrations-webhooks.hjDl1GLA_2pXsgk.webp)

3. In **Name**, enter what the webhook is for.
4. In **Endpoint URL**, enter the address of your system that receives the messages. Ask your developer for it.
5. Under **Events**, tick the events you want to receive. They are grouped as **Subscriber**, **Automation** and **Campaign**.
6. If your system can handle several events in one message, tick **Batch events**. One message then carries up to 100 events.
7. Click **Create webhook**.

   ![The Create webhook window with three events ticked](https://docs.uptools.io/_astro/07-integrations-webhook-new.03EjFqw1_1UH38D.webp)

8. Echo now shows the webhook's **Signing secret**. Copy it with **Copy** and give it to your developer, then click **Done**.

Your system can use the signing secret to check that each message really came from Echo. Like an API token, it's shown only once.

> **Good to know**
>
> - The address must start with http:// or https://, and it can use port 80, 443 or a port above 1024. Messages only go to public internet addresses, and Echo doesn't follow redirects.
> - A workspace can have at most 20 webhooks.
> - **Subscriber deleted**, **Campaign opened** and **Campaign link clicked** can only be sent in batches. When you tick one of them, **Batch events** turns on and stays on.

## Webhook events

| Event | When it's sent |
|---|---|
| **Subscriber created** | A new subscriber is added in any way: by hand, import, API or sign-up. |
| **Subscriber updated** | A subscriber's email address or field values change. |
| **Subscriber became active** | A subscriber's status changes to active, for example after confirming a sign-up. |
| **Subscriber unsubscribed** | A subscriber unsubscribes or is unsubscribed. |
| **Subscriber bounced** | A subscriber's status changes to bounced. |
| **Subscriber marked as spam** | A subscriber marks your email as spam. |
| **Subscriber deleted** | A subscriber is deleted or forgotten. After a GDPR erasure the message contains only the subscriber's ID. |
| **Subscriber added to a group** | A subscriber joins a group. |
| **Subscriber removed from a group** | A subscriber is taken out of a group. Deleting the group or the subscriber doesn't send this. |
| **Automation started** | A subscriber enters an automation workflow. |
| **Automation completed** | A subscriber finishes an automation workflow. |
| **Campaign sent** | A campaign finishes sending. |
| **Campaign opened** | A recipient opens a campaign email. Every open is sent, and the message says whether it was the first. |
| **Campaign link clicked** | A recipient clicks a link in a campaign email. |

The campaign events cover campaigns only. Emails sent by automation workflows don't send **Campaign sent**, **Campaign opened** or **Campaign link clicked**.

## How to check webhook deliveries

1. On the **Webhooks** page, click the webhook's name.
2. The **Details** box shows the address, the events, the batching and whether the webhook is on.
3. The **Deliveries** list below shows the newest messages first: their status, the events in them, how many attempts were made and the HTTP code your system answered with. Use **Status** to show only some of them, and **Refresh** to load the latest ones.

![A webhook's page with the Details box and the Deliveries list](https://docs.uptools.io/_astro/07-integrations-webhook-detail.CEuW_Foi_2pWxMd.webp)

| Status | What it means |
|---|---|
| **Pending** | The message is on its way, or Echo will try again soon. |
| **Delivered** | Your system answered with a 2xx code within 10 seconds. |
| **Failed** | Every attempt failed, or the address can't be reached (for example it isn't a public address). |

**Opening a delivery**

Click **View** in a row. The window shows the delivery ID, the attempts, the HTTP code, the content of the message (**Payload**) and the beginning of your system's answer (**Response**). If something went wrong on your side and you've fixed it, click **Resend** to send the message again. The resend is added to the list as a new delivery with its own delivery ID, so a system that skips repeated IDs processes it too. The original delivery stays as it was.

![The Delivery window](https://docs.uptools.io/_astro/07-integrations-delivery.W-AJY_bS_Z2rIMNX.webp)

> **Good to know**
>
> - If a message isn't delivered, Echo tries again 10, 100 and 1000 seconds later. After the fourth failed attempt the delivery is **Failed**.
> - **Send test** on the webhook's page sends a sample message with the webhook's first event. It's marked **Test** in the list. For a webhook that is turned off the button can't be clicked, and **Turn the webhook on to send a test.** shows below it.
> - The list keeps deliveries for 30 days.
> - **View** shows subscriber data, so it's only there for users who can also see subscribers.

## How to turn off, change or delete a webhook

- **Turn off or on:** on the **Webhooks** page, use the switch in the **Enabled** column. While a webhook is off, Echo doesn't collect events for it, and these aren't sent later either. Turning it off also fails the messages still waiting.
- **Change:** on the webhook's page, click **Edit**, change the name, address, events or batching, then click **Save changes**.
- **New signing secret:** click **Rotate secret** and confirm. The old secret stops working at once, so give the new one to your developer right away.
- **Delete:** click **Delete** and confirm. The webhook and its delivery list are deleted, and this can't be undone.

## The workflow signing key

Automation workflows can call your system too, with a webhook step. These requests are signed with one shared key for the whole workspace, the **Workflow signing key**, at the bottom of the **Webhooks** page.

1. Click **Show key**.
2. Copy the key with **Copy** and give it to your developer.
3. If the key gets into the wrong hands, click **Rotate key** and confirm. The old key stops working at once for every workflow webhook step.

Only users who manage settings can see and rotate the key. Workflow steps are covered in the [Automations](https://docs.uptools.io/echo/user-guide/automations/) chapter.

## How to import subscribers through the API

1. Open **Subscribers** and click **Add subscribers**.
2. Choose the **Import using API** tab.
3. Click **Go to documentation**. It takes you to the **API** page under **Integrations**.

![The Import using API tab](https://docs.uptools.io/_astro/07-integrations-import-api.nx6fnYue_182Bgi.webp)

With an API token, your system can add subscribers one by one (for example at checkout in your webshop) or import a whole list into a group in one request. A list imported through the API runs like a file import and shows up on the **History** tab under **Subscribers** with the result numbers.

> **Good to know**
>
> - One API import can hold up to 50,000 subscribers.
> - Subscribers your system adds one by one start as unconfirmed and get the confirmation email if double opt-in is on for API sign-ups. The setting is described in the [Settings](https://docs.uptools.io/echo/user-guide/settings/) chapter.

## FAQ

**Our developer left the company. What happens to the tokens they created?**
Once their user is removed from the workspace, their tokens stop working and the list marks them **Inactive**. Create new tokens under your own user and update them in your systems.

**Our system says the API token doesn't work. What should I check?**
Check under **Integrations**, on the **API** page, that the token is still in the list and isn't **Inactive**. If you set **Allowed IP addresses**, the request has to come from one of them. If the token still doesn't work, create a new one.

**Our system didn't get a webhook message. Where can I see why?**
Open the webhook on the **Webhooks** page and look at the **Deliveries** list. The HTTP code, and in the **View** window the **Response**, tell you what your system answered. Check that the webhook is switched on: while it's off, events aren't collected.

**How do sign-ups from the form on my website get into Echo?**
Your website's form can send the sign-ups to Echo through the API. Your developer needs an API token with **Full access** and the details from the **API** page.

**Can I see who changed a token or a webhook, or what a token did?**
Yes, on the **Activity log** tab of the users page in **Account settings**. Set **Type** to **Integrations** for token and webhook changes. Changes made through the API show the token's name in the **Who** column. The [Getting started](https://docs.uptools.io/echo/user-guide/getting-started/#the-activity-log) chapter describes the log.