מסירת וובהוקים לתור במקום לכתובת URL

למה כתובת URL היא לפעמים הבקשה הלא נכונה

הבקשה בדרך כלל מגיעה מהלקוח שלכם, לא מכם: "אפשר לשים את האירועים בתור ה-SQS שלנו?" לפעמים הסיבה היא ארכיטקטורה: הם כבר צורכים הכל דרך ברוקר, ו-handler בודד של HTTPS יהיה יוצא הדופן היחיד במערכת. ולא פחות פעמים זו מדיניות: צוות האבטחה שלהם לא יפתח פורט נכנס לצד שלישי, ושום רשימת IP מאושרים לא תשנה את התשובה. בשני המקרים, אם כל מה שאתם יודעים לשלוח זה HTTP, הבקשה שלהם הופכת לפרויקט פיתוח שלכם.

ב-HookGet זה פשוט שדה ביעד. פיזור, ניסיונות חוזרים, ציר הזמן של המסירה, שליחה חוזרת ומדידת שימוש זהים לכל סוג יעד. רק אמצעי ההעברה משתנה.

הסוגים

SQS

curl -X POST https://api.hookget.com/v1/endpoints \
  -H "authorization: Bearer $HOOKGET_KEY" \
  -H "content-type: application/json" \
  -d '{
    "kind": "sqs",
    "event_types": ["order.created"],
    "bus": {
      "target": "https://sqs.eu-central-1.amazonaws.com/123456789012/orders",
      "access_key_id": "AKIA…",
      "secret_access_key": "…"
    }
  }'

האזור (region) נגזר מכתובת התור, כך שיש שדה אחד פחות לטעות בו. ההרשאה הנכונה היא משתמש או role שכל המדיניות שלו היא sqs:SendMessage לתור האחד הזה. אנחנו מפרסמים לתור, ומפרסם לא צריך שום דבר מעבר לזה.

SNS

curl -X POST https://api.hookget.com/v1/endpoints \
  -H "authorization: Bearer $HOOKGET_KEY" \
  -H "content-type: application/json" \
  -d '{
    "kind": "sns",
    "bus": {
      "target": "arn:aws:sns:eu-central-1:123456789012:orders",
      "access_key_id": "AKIA…",
      "secret_access_key": "…"
    }
  }'

האזור מופיע בשדה הרביעי של ה-ARN של ה-topic, ומשם אנחנו לוקחים אותו.

Google Pub/Sub

curl -X POST https://api.hookget.com/v1/endpoints \
  -H "authorization: Bearer $HOOKGET_KEY" \
  -H "content-type: application/json" \
  -d '{
    "kind": "pubsub",
    "bus": {
      "project": "acme-prod",
      "topic": "orders",
      "client_email": "[email protected]",
      "private_key": "-----BEGIN PRIVATE KEY-----\n…"
    }
  }'

אנחנו מנפיקים את טוקן ה-OAuth2 ממפתח ה-service account בדיוק כמו הספריות של Google עצמה, פעם אחת לכל אצוות מסירות. המפתח עצמו נשמר מוצפן, ואף קריאה ל-API לא מחזירה אותו.

Azure Service Bus

curl -X POST https://api.hookget.com/v1/endpoints \
  -H "authorization: Bearer $HOOKGET_KEY" \
  -H "content-type: application/json" \
  -d '{
    "kind": "servicebus",
    "bus": {
      "namespace": "acme.servicebus.windows.net",
      "entity": "orders",
      "key_name": "hookget-send",
      "sas_key": "…"
    }
  }'

צרו מדיניות SAS על ה-queue או ה-topic עם הרשאת Send בלבד, ותנו לה שם שמזהה אותנו. כך, אם תרצו לבטל אותה בהמשך, זו לחיצה אחת שלא שוברת שום דבר אחר.

AWS EventBridge

curl -X POST https://api.hookget.com/v1/endpoints \
  -H "authorization: Bearer $HOOKGET_KEY" \
  -H "content-type: application/json" \
  -d '{
    "kind": "eventbridge",
    "bus": {
      "target": "arn:aws:events:eu-central-1:123456789012:event-bus/orders",
      "access_key_id": "AKIA…",
      "secret_access_key": "…"
    }
  }'

האזור יוצא מה-ARN של ה-bus. הסתייגות אחת שחשוב לדעת: EventBridge מפרק ובונה מחדש את ה-detail של האירוע בדרך לכל target, ולכן הבתים החתומים לא יכולים לעבור בתור ה-detail. הם עוברים בתוכו, בקידוד base64 בשדה data, עם מאפייני החתימה לידם, בדיוק כמו ש-Pub/Sub מחייב. מפענחים, ואז מאמתים.

Kafka, דרך ה-REST proxy

curl -X POST https://api.hookget.com/v1/endpoints \
  -H "authorization: Bearer $HOOKGET_KEY" \
  -H "content-type: application/json" \
  -d '{
    "kind": "kafka",
    "bus": {
      "target": "https://pkc-xxxxx.eu-central-1.aws.confluent.cloud:443",
      "topic": "orders",
      "username": "CLUSTER_API_KEY",
      "password": "CLUSTER_API_SECRET"
    }
  }'

נאמר את זה ישר: אנחנו לא מדברים את פרוטוקול ה-wire של Kafka. הוא דורש ספריית לקוח, ובחרנו במכוון לא להכניס אותה למוצר. אנחנו עובדים מול ה-produce API של ה-REST proxy של Confluent, ש-Confluent Cloud מארח לכל cluster, ומי שמארח בעצמו מריץ אותו כ-sidecar. מפתח הרשומה הוא מזהה המסירה, כך ששליחה חוזרת נוחתת על אותה partition. הערך הוא מעטפת שנושאת את הבתים החתומים המדויקים בקידוד base64, ועוד שלושת מאפייני החתימה. אם ל-cluster שלכם אין ממשק HTTP ואי אפשר להוסיף לו כזה, ספק שמדבר Kafka מקורי מתאים לכם יותר, ועדיף לדעת את זה מראש.

RabbitMQ, דרך ה-management API

curl -X POST https://api.hookget.com/v1/endpoints \
  -H "authorization: Bearer $HOOKGET_KEY" \
  -H "content-type: application/json" \
  -d '{
    "kind": "rabbitmq",
    "bus": {
      "target": "https://mq.example.com",
      "entity": "webhook-events",
      "vhost": "prod",
      "routing_key": "orders",
      "username": "hookget-publisher",
      "password": "…"
    }
  }'

הפרסום עובר דרך ה-HTTP API של תוסף הניהול. זו תעבורה של מסירה אחת בכל פעם, בדיוק מה שה-API הזה מיועד לו, וכל RabbitMQ מתארח (כולל CloudAMQP) חושף אותו מעל TLS. תוכן האירוע עובר ב-base64 כדי שהבתים החתומים יישמרו, ומאפייני החתימה יושבים בכותרות של הודעת ה-AMQP, שם כל צרכן בכל ספריית לקוח מוצא אותם. כברירת מחדל, ה-routing key הוא סוג האירוע, כך שהצרכנים מחברים תורים לפי אותו היגיון שהם כבר רגילים אליו.

דלי תואם S3

curl -X POST https://api.hookget.com/v1/endpoints \
  -H "authorization: Bearer $HOOKGET_KEY" \
  -H "content-type: application/json" \
  -d '{
    "kind": "bucket",
    "bucket": {
      "bucket": "acme-events",
      "prefix": "hookget/",
      "region": "eu-central-1",
      "access_key_id": "AKIA…",
      "secret_access_key": "…"
    }
  }'

כל מסירה הופכת לאובייקט אחד תחת ה-prefix. "תואם S3" כאן פשוטו כמשמעו: כל שירות שמדבר את ה-API של S3 עם SigV4 עובד, לא רק AWS.

משיכה: בלי יעד בכלל

האפשרות האחרונה מבטלת את היעד לגמרי. יעד מסוג poll משתתף בפיזור כמו כל יעד אחר, אבל שום דבר לא נשלח: הצרכן קורא מ-GET /v1/poll/{id} לפי סמן (cursor) מתי שנוח לו, ומזדהה בהרשאת גישה מפורטל הלקוחות. הוא רואה בדיוק את האירועים שיעד רגיל, שהאירועים נדחפים אליו, היה מקבל: אותם סוגי אירועים, אותם מסננים, אותו עיבוד מקדים.

curl -X POST https://api.hookget.com/v1/endpoints \
  -H "authorization: Bearer $HOOKGET_KEY" \
  -H "content-type: application/json" \
  -d '{"kind": "poll", "event_types": ["order.created"]}'

החתימה עדיין עוברת

בצד השני של תור אין כותרות HTTP, ולכן שלושת הערכים של Standard Webhooks, webhook-id, webhook-timestamp ו-webhook-signature, עוברים כמאפייני הודעה, לצד hookget-event-type. גוף ההודעה הוא בדיוק הבתים שנחתמו. צרכן שקורא מהתור מאמת עם אותה פונקציה שצרכן HTTP משתמש בה, ומדריך החתימות מביא אותה במלואה.