> ## Documentation Index
> Fetch the complete documentation index at: https://docs.groovin.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Let Groovin tell your tools when a LinkedIn message or a new connection arrives.

A webhook is an address you give Groovin. As soon as something happens on your LinkedIn account, Groovin calls that address, so your tools do not have to keep asking. It can be your own server, or a tool such as Zapier, Make or n8n.

Webhooks are the safe way to follow LinkedIn: they use none of your LinkedIn limits.

> [!NOTE]
>
> Webhooks are being rolled out by organization. If you do not see the **Webhooks** card in **Settings → MCP and API**, contact support.

## The two events

There is one address per event type:

| Event | When |
| - | - |
| [`linkedin.message.created`](https://docs.groovin.ai/reference/webhooks/message-created) | A new message in one of your one-to-one conversations, received **or sent** |
| [`linkedin.relation.created`](https://docs.groovin.ai/reference/webhooks/relation-created) | LinkedIn reports a new 1st-degree connection. Reported up to about 8 hours after it happened |

Not sent: group conversations, company page messages and sponsored messages. Imports and sync changes send no events either.

## What you receive

Each event is one `POST` with a JSON body:

```json theme={null}
{
  "id": "evt_5f0c9b2e8a714d3c9e21b7a4d6f8c013",
  "type": "linkedin.message.created",
  "timestamp": "2026-10-21T09:14:03.120Z",
  "is_test": false,
  "data": { }
}
```

* `id`: unique per event and per address, and the same on every retry. Use it to skip events you already handled.
* `timestamp`: when the event happened (the message time, or when LinkedIn reported the connection), not when it was sent to you.
* `is_test`: `true` for the test events you send from the settings page.

Headers: `content-type: application/json`, `user-agent: Groovin-Webhooks/1`, `webhook-id`, `webhook-timestamp`, `webhook-signature`.

## What to answer

* Answer with any **2xx** status **within 10 seconds**, then do your processing.
* Redirects are **not** followed: use the final address.
* Answer **410 Gone** to turn the webhook off.
* If your address requires authentication, let these requests through and [verify the signature](https://docs.groovin.ai/reference/webhooks/verify-signatures.md) instead.

## Good to know

* Events can arrive **more than once** and **out of order**: skip repeats using `webhook-id`, and order by `timestamp`.
* If one LinkedIn account is connected to several Groovin accounts, each sends its own events. To skip repeats across them, use `data.message.provider_id` for messages (or `data.message.id` when it is `null`), and the pair of LinkedIn profile ids for connections.
* After a LinkedIn reconnection, the messages received in the meantime can arrive in a burst.
* Message texts and names are written by LinkedIn users. Treat them as untrusted, especially if an AI reads them.
* New fields can be added at any time: ignore the ones you do not use. A breaking change would ship under a new event type.
* Test events carry your real `groovin_user` and `linkedin_account` blocks, and made-up message, contact and CRM data.

## Next steps

* [Set up a webhook](https://docs.groovin.ai/reference/webhooks/manage.md)
* [Verify signatures](https://docs.groovin.ai/reference/webhooks/verify-signatures.md)
* [Delivery and retries](https://docs.groovin.ai/reference/webhooks/delivery.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.