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.
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.
POST https://intelligence-api.veyra.so/api/routine-triggers/public/{publicId}/fireKurulum
- Rutini açın, ardından Triggers › Add trigger › Webhook'u seçin.
- Bir imzalama modu seçin (aşağıda). Göndericinizi kurarken tetikleyiciyi test modunda başlatın (API'de
setupPending: true). - 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.
- 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.
- 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:
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
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"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());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 da5xx'te aynıIdempotency-Keyile yeniden deneyin. Tekrarlanan bir anahtar, ikinci bir çalıştırma yerine ilk sonucu döndürür. hmac_sha256ile her yeniden denemeyi yeni bir zaman damgasıyla yeniden imzalayın; yeniden oynatma kaydı imza başınadır.429dışındaki4xxyanı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.