# Webhook events, retries and delivery limits (https://snitchfeed.com/docs/api/webhooks)



SnitchFeed can POST each new mention to your own HTTPS endpoint. This page covers what is sent and how delivery behaves. To create a destination and attach it to a feed, see [Webhooks: send new mentions to your tools](/docs/integrations/webhooks).

## Events [#events]

| Event             | When it fires                                                                                                 | Specification                                                      |
| ----------------- | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| `mention.created` | SnitchFeed **stored a new mention** for your organization and the feed it matched routes to this destination. | [Event and JSON body](/docs/api/webhooks/mention-created)          |
| `mention.resent`  | Someone **sent an existing mention** to the webhook from the app. Same JSON body as `mention.created`.        | Same body as [mention.created](/docs/api/webhooks/mention-created) |

## Payload [#payload]

Each delivery is a single `POST` with a JSON body (`Content-Type: application/json`). The top-level fields are:

| Field                                                | Description                                                                                                                    |
| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `event`                                              | `id` (unique per delivery, prefixed `whe_`), `type` (`mention.created` or `mention.resent`), `timestamp` and `version` (`1.0`) |
| `mentionId`                                          | The mention's public ID (`men_...`), the same ID the [REST API](/docs/api/introduction) uses                                   |
| `listenerId`                                         | The listener's public ID (`lis_...`)                                                                                           |
| `organizationId`                                     | Your organization                                                                                                              |
| `platform`                                           | `reddit`, `linkedin`, `twitter`, `bluesky` or `hackernews`                                                                     |
| `datePosted`, `dateFound`                            | When the post was published and when SnitchFeed found it                                                                       |
| `ai`                                                 | AI analysis: `fitScore` and `sentiment` (0 to 100), `intents`, `intentSummary`, `summary`, `language` and related fields       |
| `reddit`, `linkedin`, `x`, `bluesky` or `hackernews` | The post itself, in one object named after the platform                                                                        |

The full schema with every field is on [mention.created](/docs/api/webhooks/mention-created).

## Delivery [#delivery]

* **Success:** any `2xx` response. The response body is ignored.
* **Timeout:** SnitchFeed waits **10 seconds** for a response. A slower response counts as a failed attempt and is retried. Return `2xx` quickly and do heavy work in the background.
* **HTTPS only:** destinations must use an `https://` URL.

## Securing your endpoint [#securing-your-endpoint]

Mention webhooks are **not signed**: there is no signature header to verify. To keep others from posting fake events to your endpoint:

* Use a hard-to-guess URL with a secret path segment, for example `https://example.com/hooks/snitchfeed/3f9c1e...`, and treat that URL as a secret.
* Check that the body has the expected shape, and look up `mentionId` with `GET /v1/mentions/{id}` before acting on anything sensitive.

(OAuth revoke webhooks are signed. See [OAuth revoke webhook](/docs/api/oauth#revoke-webhook).)

## Idempotency [#idempotency]

`event.id` stays the same across every retry of one delivery. Store the IDs you have processed and skip repeats, since a delivery can arrive more than once (for example when your endpoint processed it but timed out before answering).

A `mention.resent` event is a new delivery with a new `event.id` but the same `mentionId`. Deduplicate on `mentionId` too if you only want each mention once.

## Delivery pacing [#delivery-pacing]

Each destination has two independent, **configurable** limits, set in **Integrations → Webhooks** under **Advanced** for that endpoint:

* **Requests per minute:** defaults to **10** deliveries per minute.
* **Concurrent requests:** defaults to **1** delivery in flight at a time.

Automation tools such as n8n and Zapier can fail or drop work when too many requests land at once. n8n, for example, drops anything beyond its in-flight limit (5 by default) no matter how spread out the requests are. That is why concurrency and rate are separate settings: a per-minute cap alone cannot stop a burst of simultaneous deliveries. Raise either limit for destinations that can handle more, such as Clay or Make.com scenarios backed by a higher-throughput step.

Pacing spreads different mentions over time. It is separate from **retries**, which space out repeated attempts of one failed delivery (below).

## Retries and exponential backoff [#retries-and-exponential-backoff]

If your endpoint times out, cannot be reached, or returns a **retryable** error (for example **5xx**, **429**, or most other **4xx**), SnitchFeed **retries that delivery** with **exponential backoff**.

* **Attempts:** each delivery gets **up to 10 attempts** in total, including the first POST, so up to 9 automatic retries. The `event.id` stays the same across retries.
* **Backoff:** retries start from a **30 second** base delay, and each wait roughly doubles, so short outages can recover without your URL being hammered.
* **Permanent failures (no retries):** **401**, **403**, **404** and **410** fail the delivery immediately. **404** and **410** also **deactivate** the webhook so a broken URL stops firing. **401** and **403** count toward the automatic pause after repeated failed deliveries.

## Delivery history in the app [#delivery-history-in-the-app]

To audit what was sent (timestamps, attempt count, HTTP codes, response snippets and status), open **Integrations → Webhooks** in the app and select the **Log** tab. This needs a plan that includes webhooks. **Each row is one delivery** (one mention to one endpoint). The **Attempts** column shows how many times it was POSTed, including retries. You can filter by status, endpoint and date range, page through results, and expand a row to read the stored response body when available.

![Integrations, Webhooks page with the Log tab selected, showing filters and the delivery table](https://cms.parthkoshti.com/assets/eaf32c2c-0bc6-4c56-a725-56424be5bb7f)

## OpenAPI [#openapi]

Machine-readable contract: `GET https://api.snitchfeed.com/v1/openapi.json`, under `webhooks.mention.created`.

## Related [#related]

* [Webhooks: send new mentions to your tools](/docs/integrations/webhooks): create a destination and attach it to a feed
* [Set up notifications for a feed](/docs/notifications#turn-on-alerts-for-a-feed): choose which mentions reach the webhook
* [mention.created](/docs/api/webhooks/mention-created): full payload schema
* [SnitchFeed API](/docs/api/introduction): look up mentions by ID