Integrasi Webhook

​

Alur Kerja Webhook

[Job Asinkron Selesai / Gagal] -> [Gateway Tanda Tangani Payload HMAC] -> [HTTP POST ke URL Anda] -> [Server Anda Balas 200 OK]

1. Daftarkan Endpoint: Masukkan URL server Anda dan pilih event yang ingin diterima melalui Dashboard Webhooks.
2. Simpan Secret: Salin kunci signing secret (whsec_...) yang ditampilkan saat pendaftaran untuk memvalidasi keaslian signature payload.
3. Verifikasi Signature: Validasi header webhook-signature pada server Anda menggunakan library Standard Webhooks sebelum memproses data.

​

Konfigurasi Webhook di Dashboard

1. Masuk ke akun Anda dan buka menu Webhooks di dashboard.
2. Klik tombol Tambah Webhook.
3. Masukkan URL Endpoint publik server Anda (harus menggunakan URL https:// atau http:// yang dapat dijangkau publik).
4. Pilih Event yang ingin Anda terima (misal: response.completed, batch.completed, video.completed).
5. Klik Simpan dan salin Signing Secret (whsec_...) yang muncul. Simpan secret ini di environment variables server Anda.
6. Gunakan tombol Kirim Tes untuk mengirimkan event simulasi webhook.test guna memverifikasi bahwa endpoint server Anda dapat menerima payload dengan sukses.

​

Daftar Event yang Didukung

​

Format Payload & Header

{
  "object": "event",
  "id": "evt_4f8c1a2b3d4e5f60718293a4b5c6d7e8",
  "type": "response.completed",
  "created_at": 1750287018,
  "data": {
    "id": "resp_abc123"
  }
}

​

Contoh Verifikasi Signature

import express from 'express';
import { Webhook } from 'standardwebhooks';

const app = express();
const wh = new Webhook(process.env.NEOSANTARA_WEBHOOK_SECRET);

app.post('/api/webhooks', express.raw({ type: 'application/json' }), (req, res) => {
  try {
    const event = wh.verify(req.body, {
      'webhook-id': req.header('webhook-id'),
      'webhook-timestamp': req.header('webhook-timestamp'),
      'webhook-signature': req.header('webhook-signature')
    });

    if (event.type === 'response.completed') {
      console.log('Response ID selesai:', event.data.id);
    }

    res.status(200).send('OK');
  } catch (error) {
    res.status(400).send('Invalid signature');
  }
});

from fastapi import FastAPI, Request, HTTPException
from standardwebhooks.webhooks import Webhook
import os

app = FastAPI()
wh = Webhook(os.environ["NEOSANTARA_WEBHOOK_SECRET"])

@app.post("/api/webhooks")
async def handle_webhook(request: Request):
    raw_body = await request.body()
    headers = {
        "webhook-id": request.headers.get("webhook-id"),
        "webhook-timestamp": request.headers.get("webhook-timestamp"),
        "webhook-signature": request.headers.get("webhook-signature"),
    }
    try:
        event = wh.verify(raw_body, headers)
        if event["type"] == "response.completed":
            print("Response ID selesai:", event["data"]["id"])
        return {"status": "ok"}
    except Exception:
        raise HTTPException(status_code=400, detail="Invalid signature")

​

Kebijakan Retry & Keamanan

1. Konfirmasi Cepat (HTTP 2xx): Server Anda wajib mengembalikan respons HTTP 200 OK dalam beberapa detik. Proses komputasi berat sebaiknya dialihkan ke background worker internal.
2. Otomatisasi Retry: Jika endpoint Anda mengembalikan status non-2xx atau timeout, gateway akan mencoba mengirim ulang event secara bertahap menggunakan mekanisme exponential backoff.
3. Proteksi SSRF: Gateway menolak alamat loopback (localhost, 127.0.0.1), alamat IP privat (10.0.0.0/8, 192.168.0.0/16), serta link-local demi keamanan infrastruktur.

​

Langkah Berikutnya