Webhook: makluman automatik daripada Posto

Webhook membolehkan Posto menghantar makluman ke pelayan atau alat automasi anda (cth. n8n) setiap kali sesuatu berlaku, contohnya karusel siap atau siaran diterbitkan. Webhook berada di halaman yang sama dengan kunci API, jadi memerlukan akses API & MCP. Lihat API dan MCP.

Tambah webhook

1. Buka Jenama & akaun media sosial → API & MCP (/app/settings/api), bahagian Webhook, kemudian klik Tambah webhook.
2. Isi URL titik akhir. Mesti https:// dan alamat awam; alamat peribadi atau dalaman (cth. localhost atau 192.168.x.x) ditolak. Pilih Acara, kemudian klik Tambah webhook.
3. Klik Salin rahsia untuk menyimpan rahsia tandatangan (whsec_…). Rahsia hanya dipaparkan sekali.
4. Klik Hantar ping untuk menguji. Hasilnya dipaparkan dalam Sejarah.

Acara yang boleh dipilih: carousel.ready, carousel.failed, image.ready, post.published, post.failed, credits.low, approval.decided, series.paused (jadual berulang dijeda) dan series.ended (jadual berulang selesai atau ditamatkan). Maksimum 10 webhook bagi setiap workspace.

Kandungan penghantaran

Posto menghantar POST JSON seperti ini:

{
  "id": "b2f6c1e0-…",
  "type": "post.published",
  "createdAt": "2026-10-17T12:30:41Z",
  "workspaceId": "0b6e2d14-…",
  "apiVersion": "v1",
  "data": { "scheduleId": "…", "carouselId": "…", "platform": "instagram", "permalink": "…" }
}

Pengepala yang disertakan: X-Posto-Event, X-Posto-Delivery, X-Posto-Timestamp (saat Unix) dan X-Posto-Signature. Balas 2xx dalam 10 saat; ubah hala tidak diikuti. Penghantaran yang sama mungkin tiba lebih daripada sekali, jadi abaikan id acara yang sudah diproses.

Mengesahkan tandatangan

X-Posto-Signature mengandungi v1=<hex>: HMAC-SHA256 dengan rahsia webhook ke atas teks <X-Posto-Timestamp>.<raw body>.

1. Ambil raw body tepat seperti yang diterima. Jangan parse dan tukar semula kepada teks.
2. Tolak penghantaran jika beza X-Posto-Timestamp dengan jam pelayan melebihi 5 minit (300 saat).
3. Kira HMAC, kemudian bandingkan dengan setiap nilai v1= dalam pengepala menggunakan perbandingan masa-malar (timingSafeEqual).

Contoh Node.js (Express):

import crypto from 'node:crypto'
import express from 'express'

const app = express()
const SECRET = process.env.POSTO_WEBHOOK_SECRET // whsec_...

app.post('/webhook/posto', express.raw({ type: 'application/json' }), (req, res) => {
  const ts = req.get('X-Posto-Timestamp') || ''
  const header = req.get('X-Posto-Signature') || ''
  const raw = req.body // Buffer: raw body, not parsed

  if (!/^[0-9]+$/.test(ts) || Math.abs(Date.now() / 1000 - Number(ts)) > 300) {
    return res.status(400).send('stale')
  }
  const expected = crypto.createHmac('sha256', SECRET).update(ts + '.').update(raw).digest()
  const ok = header.split(',').some((part) => {
    const m = /^v1=([0-9a-f]{64})$/.exec(part.trim())
    return m !== null && crypto.timingSafeEqual(Buffer.from(m[1], 'hex'), expected)
  })
  if (!ok) return res.status(401).send('bad signature')

  const event = JSON.parse(raw.toString('utf8'))
  res.status(200).end() // reply fast, process event.id in the background (skip ids already seen)
})

Gagal dihantar, dimatikan dan putaran rahsia

• Penghantaran yang gagal dicuba semula 6 kali (1 minit, 5 minit, 30 minit, 2 jam, 8 jam, 24 jam). Setiap cubaan direkodkan dalam Sejarah.
• Jika 3 penghantaran berturut-turut gagal dan kegagalan berlarutan 3 hari, webhook dimatikan secara automatik dan pemilik serta admin workspace menerima e-mel. Betulkan titik akhir, kemudian klik Hidupkan semula.
• Putar rahsia (dalam menu tindakan lain) mencipta rahsia baharu. Selama 24 jam pengepala memuatkan dua tandatangan (v1=<baharu>,v1=<lama>), jadi anda ada masa untuk menukar rahsia di pelayan.

Masih keliru? Hubungi [email protected].