Swimlane
Back to Help Center

Set up webhooks

A webhook makes Swimlane call a URL of yours whenever a contact is created, updated or deleted. It is the way to feed a CRM, a spreadsheet, n8n or Make without polling the API.

Before you start

  • You need a URL that accepts POST requests with a JSON body: an n8n or Make webhook, a Zapier catch hook, or your own endpoint.
  • Webhooks belong to you, not to the whole team. Each member who wants deliveries creates their own.

Create a webhook

  1. Click Settings at the bottom of the left sidebar.
  2. In the Integrations group, open Webhooks.
  3. Click Add Webhook.
  4. Paste your Webhook URL. It must start with http:// or https://.
  5. Under Events, tick at least one event: Contact Created, Contact Updated, Contact Deleted.
  6. Set Maximum Retries between 1 and 5 (see Retries below).
  7. Tick Generate secret key if you want signed requests. We recommend it for any URL on the internet.
  8. Click Create Webhook.
  9. If you asked for a secret, the Webhook Secret window shows it. Copy it now: it is never shown again. Then click Continue.

Swimlane sends a test request to your URL right after creating the webhook.

The three events

  • contact.created: a new contact enters your organization, whether you add it yourself, it comes from an import, or it appears when a new conversation syncs from LinkedIn.
  • contact.updated: the contact's own details change. This happens when you edit the contact, for example writing a note or archiving it. It also happens when an import or the inbox sync meets a contact that already exists and brings new values, such as a new headline or profile photo.
  • contact.deleted: a contact is deleted.

These three events are the only ones. There is no event for a reply, a message, a tag, a list or a pipeline stage change, and adding a tag or moving a contact in a pipeline doesn't send contact.updated. Actions done on several contacts at once (bulk edits, bulk deletes) and changes made through the public API send no event.

The request body and the signature are described in Webhook payloads and signature verification.

Test, pause, edit or delete

On each webhook in the list:

  • Click the ⋮ menu, then Test Webhook. Swimlane sends a test event and tells you "Test webhook sent successfully!" or "Test failed:" with the error. The test is only available while the webhook is active.
  • Use the switch to pause or resume it. A paused webhook receives nothing, and deliveries still waiting are dropped.
  • ⋮ → Edit changes the URL, events or retries. Tick Regenerate secret key to get a new secret (the old one stops working).
  • ⋮ → Delete removes it after confirmation.

The badges on each webhook show whether it is Active, Signed (it has a secret) and its number of attempts.

Retries

  • A delivery succeeds when your URL answers with a 2xx status within 30 seconds.
  • Maximum Retries is the total number of attempts. With 1, a failed delivery is not retried.
  • Between attempts, Swimlane waits 15 seconds, then 30, 60 and 120 seconds.
  • After the last attempt, the delivery is dropped. There is no delivery log in the app, so log incoming requests on your side.

Good to know

  • Events arrive within about a minute. Deliveries go out in batches, once a minute.
  • Every member's webhooks hear the whole organization. When a contact changes, every member of the organization who has an active webhook on that event gets a delivery, whoever made the change. If two members point at the same URL, it receives the event twice.
  • Several organizations: if you belong to more than one, your webhooks receive events from all of them.
  • Answer quickly with a 2xx and do the heavy work afterwards, so slow processing isn't counted as a failure.
  • The same event can reach you twice, for example when your server processed it but answered too late. Make your handler safe to run twice, keyed on the contact uuid.

Troubleshooting

  • Test failed: HTTP 404 / 405: the URL is wrong or doesn't accept POST. In n8n, the test URL only listens while you wait for a test event, so use the production URL for a live workflow.
  • Nothing arrives after a change: check that the webhook is active and subscribed to that event, and that the change is one that sends an event (not a tag, list or stage change, and not a bulk action).

Was this article helpful?