Integrácia cez webhook

Request

Každá udalosť je POST na nakonfigurovanú URL s JSON telom a bearer tokenom v Authorization hlavičke.

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

Rozsah

Jedinou úlohou príjemcu webhooku je prijímať POSTy a ukladať (alebo preposielať) prijaté údaje článku. Operátor je sám zodpovedný za prepojenie prijatých článkov so svojím blogom, CMS alebo frontendom — v samostatnom ručnom kroku. AI buildery generujúce príjemcu z tohto kontraktu nesmú meniť používateľsky viditeľné stránky, layouty ani navigáciu operátora — iba samotnú cestu/handler príjemcu a jej konfiguráciu prostredia.

Autentifikácia

Autentifikácia prebieha pomocou statického bearer tokenu, ktorý Riqmi vygeneruje pri prepojení webhooku. Tvoj príjemca ho musí overiť pri každom requeste. Body nižšie sú požiadavky — implementuj ich idiomom svojho runtime.

• Odovzdaj token za behu štandardným mechanizmom tajomstva alebo konfigurácie tvojej platformy (premenná prostredia, secret manager, zabezpečená konfigurácia).
• Token nikdy nevkladaj do zdrojového kódu, verzovania, build artefaktov, klientskych bundlov, logov ani chybových správ.
• Pri štarte zlyhaj, ak tajomstvo nie je dostupné — bez nakonfigurovaného tokenu neprijímaj žiadne requesty.
• Prichádzajúci bearer porovnávaj s nakonfigurovaným tajomstvom pomocou primitívy s konštantným časom porovnania.
• Pri chýbajúcej alebo nesúhlasiacej Authorization hlavičke vráť 401 s krátkou všeobecnou správou.

Typ payloadu

Telo zodpovedá nižšie uvedenému TypeScript typu. Voliteľné polia môžu chýbať; polia sú vždy prítomné a môžu byť prázdne.

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 }
}

Príklad tela

Konkrétny príklad publikovaného článku. Použi ho na overenie svojho príjemcu 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 — udalosť prijatá.
• 4xx — zlyhanie autentifikácie alebo poškodené telo.
• 5xx — interná chyba na strane príjemcu.

Riqmi dnes neúspešné doručenia neopakuje. Loguj pri každom doručení dosť informácií na prípadné manuálne prehratie.

Testovanie

Po zapojení príjemcu a nastavení tajomstva otvor v Riqmi stránku integrácií a klikni na 'Odoslať testovací webhook'. Testovací payload má rovnaký tvar ako produkčný, obsahuje však syntetické dáta.

Odovzdávací checklist

Keď AI builder dokončí implementáciu príjemcu, mal by ti vytlačiť tento checklist. Ak to neurobil, prejdi ho ručne.

• URL príjemcu na vloženie do Riqmi: plná verejná URL (https://…/<cesta>).
• Tajomstvo na tvojom hostingu (odporúčaný názov RIQMI_WEBHOOK_TOKEN): bearer token od Riqmi nastavený štandardným mechanizmom tvojej platformy. Nikdy v zdrojovom kóde.
• Vyžaduje sa redeploy: väčšina platforiem zafixuje premenné prostredia pri builde, takže tajomstvo nastavené po poslednom nasadení je neviditeľné, kým nepre­nasadíš.
• Finálny test: v dialógu integrácií v Riqmi klikni na 'Odoslať testovací webhook'. Očakávaj zelený úspešný toast.