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

# Início rápido

> Crie uma subscription de webhook, ative-a, receba o evento de ciclo de vida hub.destination.verified e confirme a entrega.

Este caminho precisa de quatro chamadas ao hub. Ele se inscreve no fato de ciclo de vida `hub.destination.verified` do próprio hub, então você não precisa de um produtor de produto separado para a primeira verificação de ponta a ponta.

Toda chamada `/v1` envia o header `Authorization: Bearer TOKEN` e `Content-Type: application/json`. O hub nunca pega o tenant de um corpo de requisição, caminho ou query.

## Antes de começar

***

Você precisa de:

* Um hub rodando e um token com as permissões `subscriptions` `get` e `post` do Streaming Hub. A leitura do catálogo também precisa de `catalog` `get`.
* Um endpoint `https://` público sob seu controle.

## As quatro chamadas

***

```
1. GET  /v1/catalog                    → find hub.destination.verified
2. POST /v1/subscriptions              → id + signingSecret
3. POST /v1/subscriptions/{id}/ping    → activate and emit the lifecycle fact
4. GET  /v1/subscriptions/{id}/health  → confirm one successful delivery
```

## 1. Encontre a chave de correspondência e a origem

***

`GET /v1/catalog`

Encontre a entrada cujo `eventKey` é `hub.destination.verified`. O `source` dela é `streaming-hub`.

Coloque o `eventKey` em `event_types` exatamente como o catálogo o serve. Não o monte a partir de `resourceType` e `eventType`. Coloque o `source` em `origin`.

## 2. Crie a subscription

***

`POST /v1/subscriptions`

Envie `X-Idempotency` com um valor único.

```json theme={null}
{
  "name": "quick-start",
  "sink_kind": "webhook",
  "endpoint": "https://hooks.example.com/lerian",
  "event_types": ["hub.destination.verified"],
  "origin": "streaming-hub"
}
```

O `event_types` recebe valores `eventKey` do catálogo, não tipos CloudEvents completos. Tanto o `event_types` quanto o `origin` são imutáveis depois da criação. O `schema_major` é opcional. O `plan_tier` tem `standard` como padrão.

A resposta `201` traz a nova `subscription` com o `id` dela e o `signingSecret` em texto claro. Guarde o segredo agora. Nenhuma rota de leitura o devolve. Uma nova tentativa com a mesma chave `X-Idempotency` devolve a mesma resposta.

## 3. Ative o destino e emita o fato de teste

***

`POST /v1/subscriptions/{id}/ping`

Um webhook novo começa em `pending_verification`. O ping envia uma sondagem assinada pelo caminho de entrega de produção. Seu endpoint deve responder com `2xx`.

```json theme={null}
{ "outcome": "ok", "statusCode": 200, "errorClass": "" }
```

O `outcome: "ok"` move a subscription para `active`. Depois que essa mudança de estado é confirmada, o hub tenta emitir `hub.destination.verified` com `ce-source: streaming-hub`. Se essa emissão de melhor esforço passar, a subscription que você acabou de criar corresponde ao fato e o recebe. Repetir o ping para uma subscription já ativa sonda o endpoint de novo, mas não emite o evento de ciclo de vida outra vez.

## 4. Confirme a entrega

***

Seu endpoint recebe um `POST` assinado com `X-Lerian-Event-Id`, `X-Lerian-Event-Type` e `X-Lerian-Delivery-Id`. Verifique o HMAC antes de confiar no corpo e deduplique pelo `X-Lerian-Event-Id`.

Depois chame `GET /v1/subscriptions/{id}/health`. Um `last_success_at` recente e uma contagem `delivered` em `delivery_outcomes` confirmam que o caminho funciona de ponta a ponta.

Uma subscription `pull` não precisa de endpoint nem de ping. Crie-a com `sink_kind: "pull"` e depois leia `GET /v1/events?subscription_id=<id>`.

Veja [Gerenciar subscriptions](https://docs.lerian.studio/pt/platform/streaming-hub/managing-subscriptions.md) e [Consumir eventos](https://docs.lerian.studio/pt/platform/streaming-hub/consuming-events.md) para ciclo de vida, assinaturas, novas tentativas e cursores.


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