# How SolidHooks works

Source: https://solidhooks.com/docs/how-it-works

> The pipeline a webhook follows, the objects involved and how they relate, and where the API, dashboard and agents fit.

SolidHooks sits between the service that sends a webhook and the endpoint that needs it. It accepts the request, checks it, stores it, and delivers it to every destination you routed it to, retrying on failure.

## The pipeline

```text
provider → source (verified) → event (stored) → connections (matched) → deliveries (retried) → destination
```

1. A provider posts to a source's ingest URL.
2. The source verifies the request, if verification is configured.
3. The request is stored as an event.
4. Connections attached to the source are matched, optionally filtered by event type.
5. Each match produces a delivery.
6. The delivery is sent to the destination and retried on failure.

## The objects

```text
organisation
├── connectors            (organisation-level, used by private destinations)
└── project
    ├── source ──┐
    │            ├── connection → destination
    │            │
    ├── event ───┘        (stored per source)
    └── delivery          (one event × one connection)
```

| Object                            | What it is                                                                                                                                                |
| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Organisation                      | The billing and tenancy boundary. API keys belong to it.                                                                                                  |
| [Project](https://solidhooks.com/docs/projects)         | A namespace inside an organisation. Sources, destinations, connections, events and deliveries each live in exactly one.                                   |
| [Source](https://solidhooks.com/docs/sources)           | An inbound endpoint with an ingest URL (`https://sdhk.events/<maskId>`). It can verify requests.                                                          |
| [Destination](https://solidhooks.com/docs/destinations) | An outbound HTTP endpoint, either public or private.                                                                                                      |
| Connector                         | An organisation-level agent you run in your network so a destination can be reached without a public URL. See [Private delivery](https://solidhooks.com/docs/private-delivery). |
| [Connection](https://solidhooks.com/docs/connections)   | Routes one source to one destination, optionally filtered by event type. A source can have many.                                                          |
| [Event](https://solidhooks.com/docs/events)             | A stored inbound request: raw body, headers and parsed payload.                                                                                           |
| [Delivery](https://solidhooks.com/docs/deliveries)      | One event shipped to one destination through one connection, with its attempts.                                                                           |

## What happens to one request

When a request reaches an ingest URL, SolidHooks works through these checks in order:

1. **Rate limit.** If the source has a rate limit set, requests over it get `429` before any storage happens. See [Rate limits](https://solidhooks.com/docs/rate-limits).
2. **Verification.** The configured verifier checks the signature. On failure the caller gets an opaque `401`, and the request is stored as an event with `status: "rejected"` and a `rejectionReason`. Rejected events are never deduplicated and never delivered. See [Verification](https://solidhooks.com/docs/verification).
3. **Idempotency.** If the source has `idempotencyKeys` and an earlier event matches, the response is `{"ok":true,"duplicate":true}` and nothing new is stored. See [Idempotency](https://solidhooks.com/docs/idempotency).
4. **Quota.** If the organisation has used its delivery quota on a plan that hard-caps, the request is refused with `429 QUOTA_EXCEEDED` before anything is stored. Duplicates never count against it. See [Plans](https://solidhooks.com/docs/plans).
5. **Store and route.** The event is stored and the response is `{"ok":true,"eventId":"evt_..."}`.

After step 5, the event gets a status:

| Status      | Meaning                                                      |
| ----------- | ------------------------------------------------------------ |
| `received`  | Matched at least one connection and was dispatched.          |
| `filtered`  | Connections exist, but their event-type filters excluded it. |
| `unmatched` | The source has no active connections.                        |
| `rejected`  | Failed verification.                                         |

## Fan-out and billing

An event routed to three connections creates three deliveries. The delivery is the billable unit, so fan-out multiplies what you use.

* Retries reuse the same delivery and are free.
* A [replay](https://solidhooks.com/docs/replay) creates new deliveries and is billed.
* Duplicate requests and rejected events create no deliveries.

## Where the API, dashboard and agents fit

All three act on the same resources.

* **API.** `https://api.solidhooks.com/v1/` with an API key. Everything the dashboard does for webhooks is available here, and the OpenAPI spec is at `/v1/spec.json`.
* **Dashboard.** [dash.solidhooks.com](https://dash.solidhooks.com) is where you sign up, create API keys, complete the first billing checkout and approve agents.
* **Agents.** An agent can use an API key a human gave it, or its own delegated identity that a human approves. See [Agent Auth](https://solidhooks.com/docs/agent-auth). The agent guide is served at `/llms-full.txt` on the API host.

Webhooks themselves only go to the ingest origin. The management API has no ingest endpoint.

## Next steps

* [Quickstart](https://solidhooks.com/docs/quickstart) — build the pipeline and send a test request
* [Sources](https://solidhooks.com/docs/sources) — providers and verification
* [Connections](https://solidhooks.com/docs/connections) — routing and filters
* [Retries](https://solidhooks.com/docs/retries) — how failed deliveries are retried