Integrace přes webhook

Request

Každá událost je POST na nakonfigurovanou URL s JSON tělem a bearer tokenem v Authorization hlavičce.

POST https://your-receiver.example.com/your-path
Authorization: Bearer <token-supplied-out-of-band>
Content-Type: application/json

Rozsah

Jediným úkolem webhook příjemce je přijímat POSTy a ukládat (nebo přeposílat) přijatá data článku. Operátor je sám zodpovědný za propojení přijatých článků se svým blogem, CMS nebo frontendem — v samostatném ručním kroku. AI buildery generující příjemce z tohoto kontraktu nesmí měnit uživatelsky viditelné stránky, layouty ani navigaci operátora — pouze samotnou cestu/handler příjemce a její konfiguraci prostředí.

Autentizace

Autentizace probíhá pomocí statického bearer tokenu, který Riqmi vygeneruje při připojení webhooku. Tvůj příjemce ho musí ověřit při každém requestu. Níže uvedené body jsou požadavky — implementuj je idiomem své runtime.

• Předej token za běhu standardním mechanismem tajemství nebo konfigurace tvé platformy (proměnná prostředí, secret manager, zabezpečená konfigurace).
• Token nikdy nevkládej do zdrojového kódu, verzování, build artefaktů, klientských bundlů, logů ani chybových hlášek.
• Při startu selži, pokud tajemství není dostupné — bez nakonfigurovaného tokenu nepřijímej žádné requesty.
• Příchozí bearer porovnávej s nakonfigurovaným tajemstvím pomocí primitivy s konstantní dobou srovnání.
• Při chybějící nebo nesouhlasící Authorization hlavičce vrať 401 s krátkou obecnou zprávou.

Typ payloadu

Tělo odpovídá níže uvedenému TypeScript typu. Volitelná pole mohou chybět; pole jsou vždy přítomna a mohou být prázdná.

type WebhookPayload = {
  timestamp: string  // ISO-8601 UTC
  data: { article: WebhookArticle }
}

type WebhookArticle = {
  id: string                    // stable unique identifier
  title: string
  slug: string
  description?: string
  excerpt?: string
  metaTitle?: string
  metaDescription?: string
  contentMarkdown?: string
  contentHtml: string
  language: string              // ISO 639-1 (e.g. "en")
  tags: string[]
  coverImage?: { url: string; altText?: string }
}

Příklad těla

Konkrétní příklad publikovaného článku. Použij ho k ověření svého příjemce proti realistickému payloadu.

{
  "timestamp": "2026-05-19T12:34:56.789Z",
  "data": {
    "article": {
      "id": "art_2k9p7d3xq8w4j",
      "title": "How to choose a CRM for a small consultancy",
      "slug": "how-to-choose-a-crm-for-a-small-consultancy",
      "description": "A short guide to picking the right CRM when your team is under twenty people.",
      "excerpt": "Small consultancies do not need enterprise CRM features — pick for adoption speed first.",
      "metaTitle": "How to choose a CRM for a small consultancy",
      "metaDescription": "Practical CRM selection criteria for consulting teams under twenty people.",
      "contentMarkdown": "# How to choose a CRM\n\nStart with adoption, not features...",
      "contentHtml": "<h1>How to choose a CRM</h1>\n<p>Start with adoption, not features...</p>",
      "language": "en",
      "tags": [
        "crm",
        "consultancy",
        "sales"
      ],
      "coverImage": {
        "url": "https://cdn.example.com/articles/crm-cover.jpg",
        "altText": "A laptop showing a CRM dashboard on a wooden desk"
      }
    }
  }
}

Návratové kódy

• 2xx — událost přijata.
• 4xx — selhání autentizace nebo poškozené tělo.
• 5xx — interní chyba na straně příjemce.

Riqmi dnes neúspěšné doručení neopakuje. Logguj při každém doručení dost informací pro případné ruční přehrání.

Testování

Po zapojení příjemce a nastavení tajemství otevři v Riqmi stránku integrací a klikni na 'Odeslat testovací webhook'. Testovací payload má stejný tvar jako produkční, obsahuje ale syntetická data.

Předávací checklist

Když AI builder dokončí implementaci příjemce, měl by ti vytisknout tento checklist. Pokud to neudělal, projdi ho ručně.

• URL příjemce pro vložení do Riqmi: plná veřejná URL (https://…/<cesta>).
• Tajemství na tvém hostingu (doporučený název RIQMI_WEBHOOK_TOKEN): bearer token od Riqmi nastavený standardním mechanismem tvé platformy. Nikdy ve zdrojovém kódu.
• Vyžadováno přenasazení: většina platforem zafixuje proměnné prostředí při buildu, takže tajemství nastavené po posledním nasazení je neviditelné, dokud nepřenasadíš.
• Finální test: v dialogu integrací v Riqmi klikni na 'Odeslat testovací webhook'. Očekávej zelený úspěšný toast.