Documentação / API / Add a webhook

Add a webhook

Be told when a post goes out or an article is published, instead of asking every thirty seconds.

4 min de leitura Paid plans

POST /api/v1/webhooks

The interesting moments happen minutes or hours after the request that caused them. Checking back every thirty seconds spends your own rate limit on a question we can simply answer.

url string OBRIGATÓRIO

Where to send events. Must be https.

events array OBRIGATÓRIO

Which events you want. At least one.

website_id string OBRIGATÓRIO

Which website these events are about.

COMECE AQUI Registering sends a test ping first and expects a 2xx. If your URL does not answer, nothing is saved and you are told why — better to find out now than to wonder later why nothing arrives.

The events

EVENTWHEN IT FIRESUSEFUL FOR

post.published A post went out on one of its channels. Logging it, or telling your team.

post.failed A post could not be published. Alerting somebody who can fix it.

post.written A post is written and waiting. Reviewing copy before it goes out.

article.published An article reached your website. Sharing it, or warming a cache.

article.written An article is written. Sending it for review.

article.failed An article could not be published. Alerting somebody.

plan.limit_reached An allowance ran out. Knowing before your calendar stalls.

Checking a delivery is really ours

Every delivery carries X-Quqi-Signature: an HMAC-SHA256 of the raw request body, using the secret from this reply. Compute the same and compare.

ATENÇÃO Sign the body exactly as it arrived. Parsing the JSON and re-encoding it produces different bytes and a different signature, and every delivery will look forged.

When your endpoint is down

A delivery is retried four times over about ten minutes. After five failures in a row the endpoint is marked failing — not switched off, because an hour of downtime should not need you to turn anything back on. Its next success clears the mark.

A 4xx is not retried: that is your server saying the request itself is wrong, and sending the identical thing again gets the identical answer.

CURL

curl -X POST https://console.quqi.io/api/v1/webhooks \
  -H "Authorization: Bearer quqi_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "website_id": "019feda8-0ca6-70d1-b927-697fa6650cda",
    "url": "https://hooks.example.com/quqi",
    "events": ["post.published", "post.failed"]
  }'

RESPONSE 201

{
  "success": true,
  "data": {
    "webhook": {
      "id": "01a0…",
      "url": "https://hooks.example.com/quqi",
      "events": ["post.published", "post.failed"],
      "status": "active"
    },
    "secret": "whsec_…",
    "note": "Store this secret. It is never shown again."
  }
}

VERIFYING (NODE)

import crypto from "crypto";

const expected = crypto
  .createHmac("sha256", process.env.QUQI_WEBHOOK_SECRET)
  .update(rawBody)          // as received, NOT re-encoded JSON
  .digest("hex");

if (expected !== req.headers["x-quqi-signature"]) {
  return res.status(401).end();
}

Esta página respondeu à sua pergunta? Sim Nem por isso

Check a task

SEGUINTE

List webhooks