All articles
Integration & Analytics

Use API keys and webhooks safely

Signalist connects to your own systems in three ways: the API , webhooks that send leads to your endpoint, and the MCP server for AI assistants. All three are under Integrations in the sidebar, in the Developer section.

API keys

Open Integrations → API.

  • Go to documentation opens the API reference at docs.signalist.io.
  • Create new API key asks for a name. The key is shown once, in Your new API key: copy it with Copy to clipboard and store it in a password manager or secret store. You cannot see it again.
  • The table lists your keys by name, the first characters of the key, and Issued at. Revoke switches a key off for good.

A key acts for your whole workspace and has no scopes or expiry date. When a key adds or changes leads, it reaches only your workspace's public lists; private lists cannot be reached with an API key. When you update a lead through the API, fields that are not lead fields are ignored, and a lead's list, prospect and status cannot be changed this way. So:

  • create one key per system or integration, named after it;
  • never paste a key into an email, chat, ticket, or code repository;
  • to replace a key, create a new one, switch your system over, then Revoke the old one;
  • if a key may have leaked, revoke it immediately.

Webhooks

Webhooks send leads from a list to a URL of yours, for example to start a workflow in another tool.

Create a webhook

  1. Open Integrations → Webhooks and click Create new webhook.
  2. Enter a Name and the Webhook URL. The URL must be a public address that starts with https:// (see "A delivery shows Not sent" below).
  3. Switch on Receives data after workflow is completed if your system sends data back; then name the custom columns it is written into.
  4. Choose the Payload format: Version 2: one event per lead (the default for new webhooks) or Version 1: list of leads (legacy). See "Choose a payload format" below.

The Create Webhook dialog with the Payload format options; Version 2: one event per lead is selected by default

  1. Confirm. The dialog Webhook created: copy your signing secret shows the secret once. Copy it into your receiver; see "Signed deliveries" below.

Send leads to it

In a list's settings, under Advanced settings → Send leads to a webhook, choose the webhook and when leads are sent: all found leads, all leads including not found, all found and unsure leads, when a lead is assigned to a campaign, or when a lead replies. You can also select leads in a list and use Add to webhook.

Each lead is sent as its own JSON request, with the same lead fields as a list export. What the request looks like around the lead depends on the webhook's payload format.

Choose a payload format

Every webhook has a Payload format. You pick it in the Create new webhook dialog and can change it later by opening the webhook for editing.

  • Version 2: one event per lead. Each delivery is one JSON object that says which event it is, gives the delivery an id, and names the time, the webhook and the list. The lead sits under data. Use it when one endpoint receives several triggers, or when your system needs to skip repeated deliveries.
  • Version 1: list of leads (legacy). The body is a JSON array that holds the lead row, as webhooks have always received it. Webhooks that existed before payload formats were introduced stay on Version 1 and receive exactly what they received before. Nothing changes for them unless you switch them.

A change of format applies to the next deliveries you send. Deliveries that were already queued before payload formats were introduced are still sent as Version 1, even to a webhook you have switched to Version 2.

Before you switch an existing webhook to Version 2, make sure your endpoint reads an object instead of an array.

What a Version 2 delivery contains

{
  "id": "2a60142d-c9e6-5f8d-8c93-e0454481e5fa",
  "type": "lead.assigned",
  "createdAt": "2026-10-13T16:10:00.000Z",
  "webhookId": 24,
  "list": { "id": 238, "name": "My list" },
  "data": { "id": 15136, "firstName": "…", "lastName": "…" }
}
FieldMeaning
idThe id of the delivery. A retry of the same delivery carries the same id, so you can use it to skip a delivery you have already handled. A new trigger, or sending the lead again with Add to webhook, is a new delivery with a new id.
typeWhat happened. See the event types below.
createdAtWhen the delivery was created, as an ISO 8601 time in UTC. The request itself can follow a few seconds later.
webhookIdThe id of the webhook that sent it.
listThe id and name of the list the lead belongs to.
dataThe lead, with the same fields as in Version 1 (and as in a list export). In rare cases, when the lead can no longer be exported, data is null.

Event types:

typeWhen it is sent
lead.qualifiedThe list's trigger is All found leads.
lead.foundThe trigger is All leads (Found & Unsure), or the trigger is All leads including not found and the lead is found or unsure.
lead.not_foundThe trigger is All leads including not found and the lead is not found (any other lead).
lead.assignedThe trigger is When assigned.
lead.repliedThe trigger is When lead replied.
lead.manual_sendYou sent the lead yourself with Add to webhook.

The type is read when the delivery is sent. If a lead's status changes while a delivery is being retried, a retry can carry another type under the same id.

See which lists a webhook is attached to

A webhook only sends leads for the lists you attach it to. The Lists column of the webhooks table shows every list a webhook is attached to, with the trigger set for that list, for example "When assigned". Click a list name to open that list's settings.

  • Three lists are shown; click + N more to see the rest, and Show less to fold them again.
  • A list that is not active carries a List inactive chip.
  • A private list of a colleague is counted ("1 private list of a colleague") without its name or a link.
  • A webhook that shows Not attached to any list receives no leads automatically. Turn it on in a list's settings under Advanced settings → Send leads to a webhook. Selecting leads and using Add to webhook still sends to it by hand.

Signed deliveries

The deliveries of every new webhook are signed with a secret that only you and Signalist know, so your receiver can check that a request came from Signalist. The Signing column of the webhooks table shows Signed, or Secret not yet viewed for a webhook created before signing was introduced (before 14 October 2026). The row menu (More actions) has Send test event, Rotate secret and, for those older webhooks, Reveal secret once.

An older webhook that shows Secret not yet viewed keeps delivering as before: unsigned, without the check for private addresses, and with redirects followed. It switches to signed delivery, with the address check and without redirects, when you choose Reveal secret once or Rotate secret, or change its URL. It never switches back. New webhooks are signed from the start.

How to check a signature, how to rotate the secret and what a test event does: Webhook signatures. Checking the signature is optional; your receiver keeps working without it.

When deliveries fail

Signalist retries a delivery when your endpoint does not answer or replies with a temporary error (408, 429, or 5xx): after 1 minute, 10 minutes, 1 hour, 6 hours, and 24 hours. Signalist waits up to 180 seconds for an answer; if none has arrived by then, the attempt counts as a failure that is retried, and the Status column shows "No complete answer within 180 seconds". Any other error is final.

  • The Status column shows Delivering, Retrying, Failing, Last delivery failed, Paused, or No deliveries yet. Under it, Last delivered and Last failed show the dates of the last successful and the last failed delivery, where there are any.
  • After 3 deliveries in a row have failed for good, the webhook's creator and your Company Admins get a notice in the app and an email: "A webhook is failing".
  • After 100 in a row, the webhook is paused and nothing more is sent. Fix or replace the URL, then press Resume.
  • Leads that could not be delivered are not sent again automatically. To send them again yourself, see "See and resend deliveries (Deliveries page)" below.

Because a delivery can be retried, your endpoint may receive the same lead twice. With Version 2, skip a delivery whose id you have already handled. With Version 1 there is no id, so match on the lead's email or LinkedIn URL.

A delivery shows Not sent

Signalist never sends a signed delivery (see "Signed deliveries" above) to a private or internal address: a URL on localhost, a loopback address such as 127.0.0.1, a private network such as 10.x or 192.168.x, a link-local address such as 169.254.x, or a name that points to one of them. Such a webhook cannot receive leads. An older webhook that still shows Secret not yet viewed is delivered as before, without this check, until it switches to signed delivery.

  • When you create or edit a webhook with such a URL, the dialog refuses it, for older webhooks too: "This URL points to a private network address, which cannot receive webhooks. Use a public URL." A URL that is not a web address reads "This is not a web address. Enter a URL that starts with https://." Nothing is saved.
  • When a signed webhook already has such a URL (for example one saved before this check), its deliveries are not sent and are given up at once, without retries. The Status column shows the reason: "Not sent: the URL points to a private network address, which cannot receive webhooks".
  • After 3 leads in a row that were not sent, the webhook's creator and your Company Admins get the notice Nothing is sent to webhook "…". After 100 in a row the webhook is paused, with the notice Webhook "…" was paused. Both say what to do: change the URL under Integrations → Webhooks. Changing the URL also lifts the pause. Leads that were not sent are not sent again automatically.
  • Send test event refuses a private URL as well, with the same text.

To fix it, open the webhook for editing, click Replace URL and paste a public URL that your receiver answers on.

A signed webhook does not follow redirects. If your URL answers with a redirect (301, 302 and so on), the delivery ends as failed with "302 Found: redirects are not followed, use the final URL", and nothing is sent to the address it points to. Use the final URL in the webhook instead. An older webhook that still shows Secret not yet viewed follows redirects as before; if you switch it to signed delivery, replace a redirecting URL with the final URL first.

See and resend deliveries (Deliveries page)

Every webhook has a Deliveries page. Open Integrations → Webhooks, find your webhook, then click View deliveries in the Status column or Deliveries in its row menu.

You need the same rights as for managing webhooks and access to Integrations. You cannot see or resend deliveries from a colleague's private list.

The page keeps deliveries for 90 days. Deliveries before 15 Oct 2026 were not recorded. Filter with Status, From and To.

Read the delivery log

ColumnWhat it shows
TimeWhen the delivery was created.
LeadThe lead sent to the webhook.
TriggerWhat caused the lead to be sent, using the same labels as the list settings.
StatusThe delivery's current state.
AttemptsThe number of delivery attempts.
Last HTTP statusThe receiver's latest HTTP status code.
Response excerptA short part of the receiver's answer.
  • Delivered: the receiver answered successfully.
  • Retrying: Signalist will resend the delivery on the normal schedule. See "When deliveries fail" above.
  • Given up: no more automatic attempts are planned. The retries were used up, the receiver gave a final error, or the delivery could not be sent.

Open a row to see its attempts and the receiver's last answer. The excerpt is the receiver's answer, not a copy of the lead data sent.

Resend one delivery

  1. Click the redeliver icon on a given-up row, or open the delivery and click Redeliver….
  2. Check the count and any skip reasons, then click Redeliver 1 delivery.

Resend all failed deliveries

  1. Click Redeliver all failed (N)…. The number in the button is the delivery count. This resends given-up deliveries.
  2. Check how many will be resent and skipped, then confirm with Redeliver N deliveries, with the number shown in the dialog (for example Redeliver 2 deliveries).

Deliveries still Retrying, leads removed from the list or deleted, and deliveries already delivered by a later redelivery are skipped. The dialog shows the counts and reasons.

Resend a date range

  1. Click Redeliver date range….
  2. Set From and To, including the times. Check the time zone shown.
  3. Keep Given up only (recommended), or choose Every delivery in the range, including delivered ones to include successful deliveries too.
  4. Check "N deliveries will be resent. M will be skipped." and the skip reasons before sending. Already delivered deliveries are skipped with the recommended option; retrying deliveries and removed leads are also skipped.
  5. Confirm with Redeliver N deliveries, with the number shown in the dialog (or Redeliver 1 delivery for one).

The "Redeliver date range" dialog: the choice of what to resend and the count of deliveries that will be resent and skipped

What a redelivery sends

A redelivery keeps the original delivery ID, so your receiver can drop duplicates it has already processed. It rebuilds the payload from the lead's current data and uses the webhook's current signing settings and secret.

A redelivery to a signed webhook is marked as one: it carries the header X-Signalist-Redelivery: true, and a Version 2 delivery also has the field "redelivery": true. A legacy webhook created before 14 Oct 2026 that has not switched to signing resends exactly like its normal deliveries, unsigned and without these marks.

A redelivery counts as one attempt. If it fails, the normal retry rules apply; see "When deliveries fail" above.

Each redelivery can include at most 500 deliveries, sent at most 5 per second. If more than 500 are selected, choose a shorter date range. Only one redelivery can run at a time for each webhook; wait for it to finish before starting another.

If the webhook is paused

A paused webhook resends nothing. The page says: "Nothing was redelivered. The webhook is paused. Resume it to redeliver. No deliveries were changed."

Click Resume on the webhook, then try the redelivery again.

The Deliveries page of a paused webhook: the message "Nothing was redelivered. The webhook is paused. Resume it to redeliver. No deliveries were changed."

Keep webhooks safe

  • Use a public HTTPS URL.
  • If your endpoint needs a secret, include it in the URL. Signalist does not log the query string.
  • The webhooks table hides the secret part of a URL: a path secret and the values after ? show as •••, for example https://hooks.example.com/services/••• or https://example.com/hook?token=•••&env=•••. A URL without a secret shows in full.
  • To change the URL, open the webhook for editing and click Replace URL, then paste the complete new URL. If you leave the URL alone, the saved one stays exactly as it was. A URL that still contains the hidden part (•••) is not saved: you see "This address still contains the hidden part (•••). Paste the full webhook address."
  • Check the signature of each delivery (Webhook signatures). For an older webhook, switch signing on first.
  • Accept only the fields you need and check them before using them.

AI assistants (MCP)

The MCP Server lets an AI assistant such as Claude work with your Signalist data. There is no key to paste: the assistant opens a Signalist page, Connect an AI application, where you click Connect. It then acts as you, with your permissions. It can also send messages and LinkedIn invitations and start campaigns on your behalf. It asks for your approval before each send or campaign start, messages and invitations it queues wait in an undo window in which you can cancel them, and the sender's daily sending limits apply; some sends can go over them only with your approval.

The assistant can also answer questions about your results and what needs attention, for example "How did my campaigns do last month?" It reads:

  • the Analytics figures: outreach KPIs for the lists, campaigns, and period you name, the overview per list and campaign, your top campaigns by reply rate, each sender's daily activity and limits, and the monthly activity of your trackers' signals;
  • the Campaigns overview figures, if your workspace has the Campaigns overview;
  • the issues your Dashboard shows, such as a disconnected LinkedIn or email account or a list that finds no results, each with a short note on how to fix it.

These figures come from the same calculation as the app, so they match the Analytics page for the same filters. As in the app, the Analytics figures need access to Analytics.

Dismiss dashboard issues through MCP

The assistant can also hide an issue from your Dashboard when you do not want to be reminded of it, and bring it back later. Ask it to dismiss or restore an issue it has read from your Dashboard, for example "Dismiss the competitors review notice."

  • Dismiss an issue hides it from your Dashboard, the same as dismissing it in the app. The assistant tells you what it dismissed and for whom.
  • Restore a dismissed issue shows it on your Dashboard again. If the issue was not dismissed, nothing changes and the assistant says so.

Most dismissals apply to you only. Some issues belong to the whole workspace, so dismissing one hides it for everyone in your company, and the assistant says which kind it is: low credits, competitors that need review, a missing owner for HubSpot notes, a missing owner privilege in Dynamics, a CRM that needs to be reconnected, and a Zoho LinkedIn field that cannot be searched. A low-credits notice comes back the next time the Dashboard checks your credits, so dismissing it does not keep it hidden for long. As in the app, you need access to Lists. Nothing is deleted or changed except whether the issue is shown, and you can restore it at any time.

Create lists through MCP

The assistant can also create a list for you, from these sources:

  • Sales Navigator: a Sales Navigator search URL. A colleague with Sales Navigator connected is needed.
  • LinkedIn people search: a search URL, or keywords with an optional title, company, school, name, and connection degree.
  • Jobs: the companies hiring for a job in a location, and the relevant people there.
  • Lookalike companies: companies similar to up to 10 seed companies (by domain) from the lead database, and the people there.

As in the app, you need access to Lists and to the source. Creating the list costs nothing and starts no run: the new list is created paused, and you start its first run in the app, which checks the setup first. A run then costs credits as it does when you create the list in the app.

Add to a tracker through MCP

The assistant can add entries to one of your trackers. As in the app, you need access to Trackers. One request adds one kind of entry, up to 100 at a time:

  • Companies by CompanyEnrich ID.
  • People by LinkedIn profile URL, added to the tracker's list. A profile Signalist does not hold yet costs credits to look up.
  • Companies by LinkedIn company page URL or by domain (for example acme.com). A company Signalist already knows is added at once; any other is added as a pending entry that the tracker's next scheduled run looks up. Values that are not a company URL or domain are reported as invalid.
  • The leads of one of your lists, either the leads themselves or the companies they work at. The list may hold at most 100 leads; for a longer list, import it in the tracker's Sources step instead. A colleague's private list and the tracker's own list cannot be used, and the tracker needs a list behind it.

The assistant answers with a report: how many entries were added, how many the tracker already had (skipped), and how many were invalid or could not be added. Repeating a request adds nothing twice. As in the app, a newly tracked company is scored and becomes part of the tracker's recurring signal scan.

To disconnect, go to Personal settings → Connected Accounts → Connected AI applications and click Disconnect. MCP access is enabled per workspace; if you see "MCP access is not enabled for your company", contact your Signalist contact.

Troubleshooting

ProblemWhat to do
An API request is rejectedCheck that the key is sent in the api-key header and has not been revoked.
A webhook shows FailingCheck that the URL is reachable and answers with a 2xx status.
A webhook is PausedFix or replace the URL, then press Resume. Leads that failed are not resent automatically. Once it runs again, you can resend them from the webhook's Deliveries page (see "See and resend deliveries (Deliveries page)"). If the reason reads "Not sent: the URL points to a private network address", replace the URL with a public one.
My receiver was down and missed leadsOpen the webhook's Deliveries page and use Redeliver all failed (N)… to resend given-up deliveries. Check the count and skip reasons before confirming.
A delivery shows "Not sent: the URL points to a private network address"The URL is on localhost, a private network or a link-local address, or a name that points to one. Open the webhook for editing, click Replace URL and paste a public URL.
"This URL points to a private network address, which cannot receive webhooks. Use a public URL."Webhooks can only go to public addresses. Use the public URL of your receiver.
"302 Found: redirects are not followed, use the final URL"Your URL answers with a redirect. Use the address the redirect points to as the webhook URL.
A webhook shows Not attached to any listIt receives nothing automatically. Attach it in a list's settings under Advanced settings → Send leads to a webhook.
"This address still contains the hidden part (•••)"The table hides the secret in a URL. Click Replace URL and paste the complete URL, or leave the URL unchanged.
The same lead arrives twiceA delivery was retried, or the lead was sent again by hand or by another trigger. With Version 2, compare the id: the same id is a retry, a different id is a new delivery. With Version 1, match on the lead's email or LinkedIn URL.
My endpoint cannot read the bodyVersion 1 sends an array that holds the lead; Version 2 sends one object with the lead under data. Open the webhook for editing and pick the Payload format your endpoint expects.
I cannot tell new leads from replies on one endpointUse Version 2 and read type (for example lead.found or lead.replied). Version 1 has no event type.
The deliveries of an older webhook carry no signatureThe webhook shows Secret not yet viewed and delivers as before. Choose Reveal secret once or Rotate secret in the row menu, or replace its URL. From then on its deliveries are signed. See Webhook signatures.
I lost the signing secret, or the signature does not matchSee Webhook signatures: Rotate secret gives a new one, and the signature is computed over the raw request body.
A key was shared by mistakeRevoke it now and create a new one.
The AI assistant cannot read Analytics figuresCheck that your role has access to Analytics in Signalist.
The AI assistant cannot dismiss or restore a dashboard issueCheck that your role has access to Lists, and ask the assistant to read your Dashboard issues first so it uses an issue that exists.
The AI assistant cannot create a list from a sourceCheck that your role has access to Lists and to that source, and that a LinkedIn account (with Sales Navigator for Sales Navigator lists) is connected.
The AI assistant cannot add the leads of a list to a trackerCheck that the list has at most 100 leads, is not a colleague's private list, and that the tracker has a list behind it.

Frequently asked questions

Can I limit what an API key can do?

No. A key acts for the whole workspace. Create one key per system so you can revoke each one on its own.

How do I rotate a key?

Create a new key, switch your system to it, then revoke the old key.

Are failed webhook deliveries retried?

Yes, up to five times over 24 hours for temporary errors. After that the lead is not sent again automatically. A delivery that is "Not sent" because the URL is on a private address is not retried at all.

How do I resend deliveries my receiver missed?

Open the webhook's Deliveries page and use Redeliver all failed (N)…, or Redeliver date range… for a chosen period. See "See and resend deliveries (Deliveries page)" above.

Deliveries before 15 Oct 2026 were not recorded, so you cannot see or redeliver them on this page. To send those leads again, select them in the list and use Add to webhook. That creates new deliveries with new IDs, so your receiver should check for duplicates.

Can a webhook send to a server on my own network?

No. Signalist sends webhooks only to public addresses. A URL on localhost, a private network or a link-local address is refused when you save it, and the deliveries of a signed webhook to such a URL are shown as "Not sent". Use a public URL, for example one your gateway or tunnel exposes.

Are my webhook deliveries signed?

Yes, for every new webhook. A webhook created before 14 October 2026 delivers unsigned, as before, until you reveal or rotate its signing secret or change its URL; from then on it is signed. Your receiver can check the signature, but does not have to. See Webhook signatures.

Which payload format should I choose for a new webhook?

Version 2, which is the default: every delivery names its event type and carries an id you can use to skip repeats. Choose Version 1 only if your endpoint is built to read an array of lead rows.

Will my existing webhooks change?

No, not unless you change them. Their payload stays as it is: webhooks that existed before payload formats were introduced stay on Version 1 and receive the same body as before, and they change only if you open the webhook for editing and pick Version 2. They are also still delivered unsigned, as before, until you reveal or rotate the signing secret or change the URL. After that they are signed and checked like a new webhook, and this stays.

Can I go back to Version 1?

Yes. Open the webhook for editing, pick Version 1: list of leads (legacy), and confirm. The next deliveries are sent as an array again.

Why can't I see the secret in my webhook's URL any more?

The table hides it so that nobody who opens the page can read it. The secret is still stored and still used for deliveries. To change it, use Replace URL and paste the complete new URL.

Can the AI assistant send messages?

Yes. It can send messages and LinkedIn invitations and start campaigns on your behalf, with the same safeguards: it asks for your approval before each send or campaign start, messages and invitations it queues wait in an undo window in which you can cancel them, and the sender's daily sending limits apply. To cut off its access at any time, disconnect it under Personal settings → Connected Accounts → Connected AI applications.

Can the AI assistant dismiss an issue on my Dashboard?

Yes. It can dismiss an issue and restore it again. Most dismissals apply to you only; a few issue types (such as low credits or a CRM that needs to be reconnected) belong to the whole workspace and are hidden for everyone in your company. A low-credits notice comes back the next time the Dashboard checks your credits.

Does the AI assistant start the run of a list it creates?

No. A list created through MCP is paused. You start its first run in the app, which checks the list's setup first.

Do the assistant's numbers match the Analytics page?

Yes. The assistant reads the same figures the Analytics page shows. Ask for the same lists, campaigns, and period to compare them.