İnceleme 2026-11-11 · API sürümü 2026-11-09 · Markdown oku
Müşteri webhook'ları
Çalışma alanınız için giden olay teslimi. Bir HTTPS uç noktası kaydedin, tek kullanımlık imzalama gizli anahtarını doğrulayın ve sınırlı yeniden denemelerle imzalı olaylar alın.
Uç nokta kaydetme
curl -s -X POST -H "Authorization: Bearer $PUBLISHER_KEY" \
-H "Idempotency-Key: $(uuidgen)" -H "Content-Type: application/json" \
$BASE/webhooks -d '{"url": "https://example.com/hooks/autoposted"}'
- İmzalama gizli anahtarı (
whsec_…) bir kez döndürülür: ilk başarılı oluşturma yanıtında. Saklayın; aynı oluşturmanın idempotent yeniden oynatımı uç noktayı gizli anahtar olmadan döndürür ve bir daha gösterilemez. - Hedefler HTTPS, herkese açık şekilde çözümlenebilir ve gömülü kimlik bilgisi içermeyen olmalıdır. Özel, loopback, link-local (bulut üst verisi dâhil), unique-local ve multicast adreslerine yapılan istekler, hiçbir bağlantı kurulmadan önce reddedilir ve yönlendirmeler asla takip edilmez.
- Kayıt, o uç nokta için
eventTypesfiltresinden bağımsız olarak hedefli birwebhook.verificationolayı kuyruğa ekler. Sıradan olaylar, uç noktanız doğrulamayı 2xx ile yanıtladıktan sonra akmaya başlar.
Teslimatları doğrulama
Her istek şunları taşır:
| Başlık | Anlam |
|---|---|
x-publisher-event-id | Kararlı olay kimliği: yeniden denemeler ve yeniden oynatmalar arasında özdeş |
x-publisher-event-type | Olay türü, ör. post.published |
x-publisher-timestamp | Unix saniyeleri |
x-publisher-signature | t=<ts>,v1=<hex> |
İmza; imzalama gizli anahtarınız kullanılarak ${t}.${event_id}.${raw_body}
üzerinden HMAC-SHA256'dır. ±300 saniyelik toleransla doğrulayın ve dışındaki
yeniden oynatmaları reddedin. Node örneği:
import { createHmac, timingSafeEqual } from 'node:crypto';
function verify(secret, headers, rawBody) {
const m = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(headers['x-publisher-signature']);
if (!m) return false;
const [t, v1] = [Number(m[1]), m[2]];
if (Math.abs(Date.now() / 1000 - t) > 300) return false;
const expected = createHmac('sha256', secret)
.update(`${t}.${headers['x-publisher-event-id']}.${rawBody}`)
.digest('hex');
return timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}
Ayrıştırmadan önce her zaman ham istek gövdesine karşı doğrulayın.
Olay zarfı
{
"id": "0192d0d0-0000-7000-8000-00000000000f",
"type": "post.published",
"createdAt": "2026-11-09T12:00:01Z",
"apiVersion": "2026-11-09",
"data": { "postId": "…", "deliveryId": "…", "accountId": "…" }
}
Başlangıç olay kataloğu (genişletilebilir; kayıtta eventTypes filtreler):
webhook.verification: doğrulama yükü; uç noktayı etkinleştirmek için 2xx yanıtlayınpost.published: yerel makbuzla doğrulanmış tek hedefdelivery.failed: son olarak başarısız olan tek hedefdelivery.requires_action: onay/yeniden bağlantı/geç inceleme gerekiyor
Toplam gönderi sonuçları (post.partially_published, post.failed) henüz
üretilmiyor; yalnızca bir üretici var olduğunda burada belgelenir, bu nedenle onlara
güvenmeyin. Yukarıdaki hedef başına olaylara abone olun ve toplu durumu gönderinin
teslimat sonuçlarından türetin.
Yeniden denemeler, yeniden oynatma ve devre dışı bırakma
- Denemeler: hemen, ardından +1m, +5m, +30m, +2h, +8h. Yeniden denemeler, güvenli biçimde tekilleştirebilmeniz için aynı olay kimliğini ve bayt düzeyinde özdeş gövdeyi yeniden kullanır.
- 2xx = teslim edildi. 429/5xx/zaman aşımı yeniden denenir. Diğer 4xx'ler o olay için kalıcı olarak başarısız olur (uç noktayı düzeltin, sonra yeniden oynatın).
- 410 Gone uç noktayı devre dışı bırakır: ona başka olay kuyruğa eklenmez.
- İç webhook servisi üzerinden operatör yetkili yeniden oynatma, olayı özgün kimliğiyle yeniden gönderir. Aktif kiralanmış bir yürütülmekte olan deneme asla geri alınmaz; yeniden oynatma, olayın meşgul olduğunu ve kısa süre içinde yeniden denenebileceğini bildirir.
Operasyonel notlar
- Teslimat tanılamaları yalnızca güvenli sonuç kodları saklar: asla sizin gizli anahtarınızı, imzaları, istek başlıklarını veya yanıt gövdelerini değil. Yükler ayrıca temizlenir: kuyruğa alınmadan önce sağlayıcı/OAuth gizli anahtarları ve medya ön-imza URL'leri çıkarılır.
- Uç noktalar çalışma alanı kapsamlıdır: başka bir çalışma alanından bir uç nokta UUID'sine sahip olmak hiçbir şey yapmaz.
- Teslim, kabul edilen her olay gerçekleşimi için en az bir kezdir;
x-publisher-event-idüzerinde tekilleştirin.
Geliştirici araçlarının kullanılabilirliği
Developers sayfası; çalışma alanı API anahtarlarını ve webhook uç noktalarını imzalama-gizli anahtarı şifreleme yapılandırmasından bağımsız listeler. Webhook oluşturmak, geçerli bir sunucu şifreleme yapılandırması gerektirir; yapılandırma uyarısını çözmek için dağıtım operatörüne danışın. API anahtarı yönetimi kullanılabilir kalır. Mevcut imzalama gizli anahtarları bir daha asla gösterilmez.