Rutin tetikleme webhook'u

Bir rutini kendi sistemlerinizden başlatın. Adres, beş imzalama modu, başlıklar, yük, yanıtlar, yeniden denemeler ve yeniden oynatma koruması; curl, JavaScript ve Python'da imzalama koduyla.

Veyra Docs TeamGüncellendi 3 dk okumaSürüm 3 · Geçmiş

Bir webhook tetikleyicisi, herhangi bir sistemin bir rutini başlatmasını sağlar: bir izleme alarmı, bir CI hattı, bir form, başka bir ürün. Her teslimat bir çalıştırma oluşturur; gönderdiğiniz JSON çalıştırmada saklanır ve agent'a veri olarak gösterilir.

HTTP
POST https://intelligence-api.veyra.so/api/routine-triggers/public/{publicId}/fire

Kurulum

  1. Rutini açın, ardından Triggers › Add trigger › Webhook'u seçin.
  2. Bir imzalama modu seçin (aşağıda). Göndericinizi kurarken tetikleyiciyi test modunda başlatın (API'de setupPending: true).
  3. URL'yi ve sırrı kopyalayın. Sır yalnızca bir kez gösterilir; Rotate secret yenisini üretir ve eskisi hemen çalışmayı bırakır.
  4. Bir test teslimatı gönderin. Test modunda denetlenir ve kaydedilir ama çalıştırma başlatmaz; böylece kimlik doğrulamayı güvenle doğrulayabilirsiniz.
  5. Test modunu kapatın. Bundan sonra kabul edilen her teslimat bir çalıştırma başlatır.

İmzalama modları

Mod Gönderin Ne zaman seçilir
bearer (varsayılan) Authorization: Bearer <secret> Göndericiniz bir başlık ayarlayabiliyorsa.
hmac_sha256 X-Veyra-Timestamp ve X-Veyra-Signature Yeniden oynatılamayan, imzalı ve süreyle sınırlı istekler istiyorsanız.
github_hmac X-Hub-Signature-256: sha256=<hex> Gönderici GitHub ya da Sentry gibi imzalıyorsa (ham gövdenin HMAC'i).
app_webhook Bearer ya da X-Hub-Signature-256 Bağlı bir uygulama olay iletiyorsa; yük agent'a aktarılır.
none Hiçbir şey Yalnızca kişiler seçebilir; sır yalnızca URL'nin kendisidir. Agent'lar kimlik doğrulamasız tetikleyici oluşturamaz.

hmac_sha256

İmzayı zaman damgası, bir nokta ve gövdenin tam baytları üzerinden hesaplayın:

Text
signature = hex( HMAC-SHA256( secret, timestamp + "." + raw_body ) )

X-Veyra-Timestamp: <timestamp> (Unix saniyesi ya da milisaniyesi) ve X-Veyra-Signature: sha256=<signature> gönderin. Tetikleyicinin yeniden oynatma penceresinin dışındaki bir zaman damgası reddedilir (30 ile 86.400 arasında ayarlamadıysanız 300 saniye) ve aynı imzalı istek yalnızca bir kez kabul edilir.

Başlıklar

Başlık Zorunlu Anlamı
Content-Type: application/json Evet Gövde bir JSON nesnesi olmalıdır.
Authorization bearer, app_webhook Bearer <secret>.
X-Veyra-Timestamp hmac_sha256 İmzalamanın Unix zamanı.
X-Veyra-Signature hmac_sha256 sha256= ve onaltılık HMAC. github_hmac için de kabul edilir.
X-Hub-Signature-256 github_hmac sha256= ve ham gövdenin onaltılık HMAC'i.
Idempotency-Key Önerilir Bu olay için sizin kimliğiniz. Tekrarı ilk sonucu döndürür. Varsa X-GitHub-Delivery kullanılır.
X-Veyra-Idempotency-Scope Hayır trigger (varsayılan): anahtarlar tetikleyici başına benzersizdir. routine: rutinin tüm tetikleyicileri arasında benzersizdir.

Gövde

10 MB'a kadar herhangi bir JSON nesnesi. İki alanın kendine özgü anlamı vardır:

  • variables: rutinin değişkenleri için değerlerden oluşan bir nesne, örneğin {"variables": {"ticket": "SUP-812"}}.
  • Geri kalan her şey çalıştırmada yükü olarak saklanır.

İmzalı bir istek gönderin

curl
URL="https://intelligence-api.veyra.so/api/routine-triggers/public/$PUBLIC_ID/fire"
BODY='{"variables":{"ticket":"SUP-812"},"severity":"high"}'
TS=$(date +%s)
SIG=$(printf '%s.%s' "$TS" "$BODY" | openssl dgst -sha256 -hmac "$TRIGGER_SECRET" -hex | sed 's/^.* //')

curl -X POST "$URL" \
  -H "Content-Type: application/json" \
  -H "X-Veyra-Timestamp: $TS" \
  -H "X-Veyra-Signature: sha256=$SIG" \
  -H "Idempotency-Key: SUP-812" \
  --data-binary "$BODY"
JavaScript
import { createHmac } from "node:crypto";

const body = JSON.stringify({ variables: { ticket: "SUP-812" }, severity: "high" });
const timestamp = String(Math.floor(Date.now() / 1000));
const signature = createHmac("sha256", process.env.VEYRA_TRIGGER_SECRET)
  .update(`${timestamp}.`)
  .update(body)
  .digest("hex");

const response = await fetch(url, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-Veyra-Timestamp": timestamp,
    "X-Veyra-Signature": `sha256=${signature}`,
    "Idempotency-Key": "SUP-812",
  },
  body, // imzaladığınız baytların aynısını gönderin
});
console.log(response.status, await response.json());
Python
import hashlib, hmac, json, os, time
import requests

secret = os.environ["VEYRA_TRIGGER_SECRET"].encode()
body = json.dumps({"variables": {"ticket": "SUP-812"}, "severity": "high"}, separators=(",", ":")).encode()
timestamp = str(int(time.time()))
signature = hmac.new(secret, timestamp.encode() + b"." + body, hashlib.sha256).hexdigest()

response = requests.post(
    url,
    data=body,  # imzaladığınız baytların aynısını gönderin
    headers={
        "Content-Type": "application/json",
        "X-Veyra-Timestamp": timestamp,
        "X-Veyra-Signature": f"sha256={signature}",
        "Idempotency-Key": "SUP-812",
    },
    timeout=15,
)
print(response.status_code, response.json())

bearer ile yalnızca Authorization: Bearer $TRIGGER_SECRET ve JSON'u gönderin.

Yanıtlar

Durum Gövde Anlamı
202 Rutin çalıştırması Kabul edildi. Çalıştırmanın status alanı ne olduğunu söyler (örneğin bir görev oluşturuldu ya da teslimat aktif bir çalıştırmayla birleştirildi).
202 {"status": "test_received", "test": true} Test modu: kimlik doğrulandı ve kaydedildi, çalıştırma başlatılmadı.
202 {"status": "ignored"} Bağlı bir uygulama, tetikleyicinin abone olmadığı bir olay gönderdi.
400 {"error": ...} Gövde bir JSON nesnesi değil ya da bir başlığın değeri yanlış.
401 {"error": ...} Sır ya da imza eksik veya yanlış, ya da zaman damgası pencerenin dışında.
404 {"error": ...} Böyle bir tetikleyici yok.
409 {"error": ...} Rutin arşivlenmiş ya da tetikleyici veya rutin aktif değil.
415 {"error": ...} Content-Type, application/json değil.

Reddedilen teslimatlar tetikleyicide (last delivery: rejected) ve aktivite günlüğünde kaydedilir; böylece gönderilen içeriği açığa çıkarmadan başarısız denemeleri görebilirsiniz.

Yeniden denemeler ve kopyalar

  • Ağ hatasında, zaman aşımında, 429'da ya da 5xx'te aynı Idempotency-Key ile yeniden deneyin. Tekrarlanan bir anahtar, ikinci bir çalıştırma yerine ilk sonucu döndürür.
  • hmac_sha256 ile her yeniden denemeyi yeni bir zaman damgasıyla yeniden imzalayın; yeniden oynatma kaydı imza başınadır.
  • 429 dışındaki 4xx yanıtlarını yeniden denemeyin; bunun yerine isteği düzeltin.

Agent ne görür

Çalıştırmanın görevi rutinin isteğini içerir. Gönderdiğiniz yük veri olarak eklenir; dışarıdan geldiği ve talimat olarak izlenmemesi gerektiği işaretlenir. Rutine, yükü nasıl ele alacağına dair açık talimatlar verin.

API referansındaki Fire a public routine trigger, Create a routine trigger ve Rotate a routine trigger secret sayfalarına bakın.

GelenRutinlerWebhook'lar