Webhook integration

Request

Every event is a POST to the URL you configured, with a JSON body and a bearer token in the Authorization header.

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

Scope

The webhook receiver's only job is to accept POSTs and persist (or forward) the received article data. The operator is responsible for wiring received articles into their blog, CMS, or frontend themselves in a separate manual step. AI builders generating a receiver from this contract must not modify the operator's user-facing pages, layouts, or navigation — only the receiver route/handler and its environment configuration.

Authentication

Authentication is a static bearer token Riqmi generates when you connect the webhook. Your receiver must validate it on every request. The constraints below are requirements — express each one in the idiom your runtime provides.

• Supply the token at runtime via your platform's standard secret or configuration mechanism (environment variable, secret manager, secure config).
• Never embed the token in source code, version control, build artifacts, client-side bundles, logs or error messages.
• Fail closed on startup if the secret is unavailable — do not accept requests when no token is configured.
• Compare the incoming bearer with the configured secret using a constant-time comparison primitive.
• Respond 401 with a short generic message on a missing or mismatched Authorization header.

Payload type

The body conforms to the TypeScript type below. Optional fields may be omitted; arrays are always present and may be empty.

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

Example body

A concrete example of a published article. Use it to validate your receiver against a realistic payload.

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

Response codes

• 2xx — event accepted.
• 4xx — authentication failure or malformed body.
• 5xx — internal failure on the receiver side.

Riqmi does not retry failed deliveries today. Log enough on each delivery to support manual replay if needed.

Testing

After wiring the receiver and supplying the secret, open the integrations page in Riqmi and click 'Send test webhook'. The test payload has the same shape as production but contains synthetic data.

Operator handoff checklist

When an AI builder finishes implementing the receiver it should print this checklist back to you. If your AI did not, walk through it manually.

• Receiver URL to paste into Riqmi: the full public URL (https://…/<path>).
• Secret to set on your host (recommended name RIQMI_WEBHOOK_TOKEN): the bearer token Riqmi gave you, set via your platform's standard mechanism. Never in source.
• Redeploy required: most platforms snapshot env vars at build time, so a secret added after the last deploy is invisible until you redeploy.
• Final test: in the Riqmi integrations modal, click 'Send test webhook'. Expect a green success toast.