İmzalı webhook'ların doğrulanması
Workflow Webhooks, Shopify Flow çalışmadan önce webhook HMAC imzasını doğrular: 22 yerleşik sağlayıcı ve diğer hizmetler için özel imza desteği.
Birçok hizmet, gönderdiği webhook’ları imzalar; böylece alıcı, bir isteğin gerçekten kendilerinden geldiğini ve yol boyunca değiştirilmediğini doğrulayabilir. Bir webhook’un kimlik doğrulama yöntemini HMAC olarak ayarladığınızda, uygulama, herhangi bir veri Shopify Flow’a ulaşmadan önce bu imzayı kontrol eder. Kontrolden geçemeyen bir istek, 401 hatasıyla reddedilir ve iş akışı asla çalıştırılmaz.
Bunu ayarlamanın iki yolu vardır: listeden göndereni seçin ya da nasıl imzaladığını açıklayın.
Yerleşik sağlayıcılar
İmza sağlayıcısı bölümünden sağlayıcıyı seçin ve imza gizli anahtarını yapıştırın. Uygulama daha sonra bu sağlayıcının belgeleri düzenleme biçimini (doğru başlık, kodlama, imzalanmış içerik ve tekrar oynatma aralığı) doğrular; dolayısıyla yapılandırmanız gereken başka bir şey yoktur. Her sağlayıcının, uç noktanın oluşturulmasından Shopify Flow iş akışının oluşturulmasına kadar kendi kurulum kılavuzu mevcuttur.
Her kılavuzda, uygulamanın o gönderenle ilgili tam olarak neleri kontrol ettiği ve imzalamaya yönelik gizli anahtarının nerede bulunabileceği ayrıntılı olarak belirtilmiştir.
Özel imza: diğer tüm gönderenler
Göndereniniz listede yoksa, Özel imza seçeneğini seçin ve nasıl imzalandığını açıklayın. Servis sağlayıcınızın belgelerinde şuna benzer bir satır yer alacaktır:
X-Acme-Signature = hex(hmac_sha256(secret, timestamp + "." + body))
Bu tek satır, tüm alanlara yanıt veriyor:
| Ayarlar | Örnekten | Bunun anlamı nedir? |
|---|---|---|
| İmza başlığı | X-Acme-Signature |
İmzayı taşıyan başlık |
| Algoritma | hmac_sha256 |
SHA-256, SHA-1 veya SHA-512 |
| Kodlama | hex |
hex, base64 veya base64url |
| İmzalı veri yükü | {timestamp}.{body} |
İmzalanan metnin tam metni |
| Zaman damgası | X-Acme-Timestamp gibi bir başlık |
timestamp değerinin gittiği yer |
| Tekrar oynatma toleransı | 300 saniye | Bundan daha eski talepleri reddet |
İmzalanmış yük
Göndericinin imzaladığı kısmı şu yer tutucuları kullanarak yazın:
| Yer tutucu | Şu hale gelir |
|---|---|
{body} |
İşlenmemiş istek gövdesi, bayt bayt. Zorunludur. |
{timestamp} |
Başlıktaki veya imza başlığındaki zaman damgası |
{url} |
Bu webhook’un URL’si, gönderen tarafında girdiğiniz şekliyle |
{header:name} |
Başka bir istek başlığının değeri |
Yaygın biçimler: {body}, {timestamp}.{body}, {timestamp}{body}, v0:{timestamp}:{body}, {header:webhook-id}.{timestamp}.{body}. Bir sağlayıcıdan başla seçeneğini kullanarak benzer bir biçimi kopyalayın ve yalnızca farklı olan kısımları değiştirin.
İmzanın bulunduğu yer
- Basit: Başlık değeri imzadır; isteğe bağlı olarak,
sha256=veyav1,gibi sizin belirlediğiniz bir önekten sonra gelir. - Anahtar = değer: Başlık,
t=1700000000,v1=abc...gibi çiftleri içerir. İmzayı barındıran anahtarın adını (v1), isteğe bağlı olarak zaman damgasını barındıran anahtarın adını (t) ve çiftlerin,mi yoksa;ile mi ayrılacağını belirtin.
Bir başlıkta, boşluklarla ayrılmış birden fazla imza bulunuyorsa (bazı gönderenler, gizli anahtarı değiştirirken bunu yapar), bunlardan herhangi biri eşleşirse kabul edilir.
Sır
Genellikle, gönderenin gösterdiği şekilde şifreyi yapıştırırsınız. Bazı gönderenler, whsec_... gibi bir önek içeren Base64 kodlu bir anahtar verir: Base64 kodlu seçeneğini seçin ve kaldırmak istediğiniz öneki girin.
Canlıya geçmeden önce test etme
İmza denetleyicisi, ayarların altında yer alır ve kaydedilmemiş değişikliklerle çalışır.
- Gerçek bir isteğin gövdesini ve başlıklarını yapıştırın ve Doğrula düğmesine basın. Her adımı görebilirsiniz - başlık bulundu, imza okundu, zaman damgası aralıkta, yük oluşturuldu, imzalar karşılaştırıldı - ve imzalanmış olan metnin tam metnini de görebilirsiniz; böylece bir uyuşmazlık durumunda, sadece “geçersiz imza” gibi genel bir uyarı yerine, sorunun tam olarak nerede olduğunu görebilirsiniz.
- Geçerli bir örnek oluştur seçeneği, mevcut ayarlarınız için doğru şekilde imzalanmış başlıklar ve çalıştırılmaya hazır bir
curlkomutu üretir. Bu istek kabul edilirse, yapılandırmanız uçtan uca tutarlı demektir.
Test kullanıcısı hiçbir zaman bir iş akışını başlatmaz, Geçmiş’e hiçbir şey kaydetmez ve planınızın kotasından düşülmez.
İmza uyuşmuyor. Nereye bakmalıyım?
Şu sırayla: şifre (en yaygın neden; fazladan bir boşluk veya yanlış ortam anahtarı dahil), **imzalı **veri yükü (zaman damgası ile gövde arasında eksik bir . veya :), kodlama (hex ve base64), ve gönderen ile uygulama arasında bir şeyin gövdeyi değiştirip değiştirmediği. İmzalar ham baytları kapsar, bu nedenle JSON'u yeniden biçimlendiren bir proxy, imzaları bozar.
İstekler, "zaman damgası tolerans aralığı dışında" hatasıyla başarısız oluyor
Göndericinin saati yanlış ayarlanmış, istek gecikmiş ya da eski bir zaman damgasıyla yeniden denenmiş ya da zaman damgası birimi yanlış. Göndericinizin saniye, milisaniye mi yoksa ISO tarihi mi kullandığını kontrol edin.
Göndericimin önce bir doğrulama el sıkışması yapması gerekiyor
Bazı hizmetler (Zoom, Dropbox, Asana, Trello, Notion), herhangi bir olay iletmeden önce uç noktanın yanıtlaması gereken bir doğrulama talebi gönderir; her biri bunu kendine özgü bir şekilde yapar. Bu nedenle, bu hizmetler tek tıklamayla kullanılabilen sağlayıcılar olarak sunulmamaktadır. Bu hizmetlerden birine ihtiyacınız varsa, gönderen adınızı belirterek destek ekibiyle iletişime geçin.
İmza herhangi bir yerde saklanıyor mu?
Hayır. İmza başlıkları, Geçmiş bölümünde ve Canlı İstek Denetleyicisi’nde gizlenir; çünkü bir imza, tolerans aralığı içinde yeniden oynatılabilir.