Если вы создаете приложения, управляемые событиями, вы, вероятно, рассматривали возможность создания их на бессерверной платформе. Он действительно хорошо подходит для небольших функций, запускаемых при входящем событии, обработки данных и последующего бездействия. Вместо создания собственного цикла обработки событий, который простаивает между событиями, вы передаете всю эту логику бессерверному провайдеру. Будучи ленивым разработчиком, я предпочитаю писать как можно меньше кода 😅.
Поэтому меня не удивит, что большинство моих веб-хуков работают без сервера, а не на моей локальной машине или на виртуальной машине, которую мне нужно где-то обслуживать. Недавно мы использовали Netlify здесь, в Fidel, для нашего предварительного просмотра документации, поэтому я решил попробовать функции Netlify. В этом сообщении блога я собираюсь использовать их с JavaScript для получения событий веб-перехватчика от API.
Что такое вебхуки?
Прежде чем мы начнем, давайте немного освежим в памяти то, что на самом деле представляют собой вебхуки. Если вы думаете об API как о черных ящиках, которые позволяют вам вызывать их время от времени, вебхуки — это механизм, который они используют, чтобы перезвонить вам, когда им есть что вам сказать. Когда вы хотите попросить API сделать что-то для вашего приложения, вы делаете HTTP-запрос к конечной точке API и отправляете некоторые данные. Когда API хочет отправить какие-то данные в ваше приложение, и вам не нужно запрашивать их каждую секунду (также известное как опрос), они делают HTTP-запрос к вашему URL-адресу веб-перехватчика.
Теперь, когда мы знаем, что такое веб-перехватчики, давайте рассмотрим несколько вещей, которые вам понадобятся на этом пути получения событий веб-перехватчиков с помощью функций Netlify и JavaScript.
Предпосылки
- Node.js установлен
- Счет Netlify
- Счет Фиделя
Создание функции Netlify
Настройка интерфейса командной строки Netlify
Я собираюсь использовать Netlify CLI для создания и развертывания функции. Если он у вас еще не установлен, сейчас самое время это сделать.
netlify loginПосле того, как вы установили CLI, вам также необходимо будет аутентифицировать его с помощью вашей учетной записи Netlify.
netlify loginОткроется окно браузера с запросом разрешения на доступ к Netlify от вашего имени. Давай, разреши это.
Нам также нужно создать файл `netlify.toml` в корне папки вашего проекта, и мы включим там функции.
[build]
functions = "functions"
publish = "dist"Создайте функцию Netlify
Теперь, когда мы все настроили Netlify, мы можем продолжить и создать функцию с помощью CLI.
netlify functions:createЭто создаст интерактивную подсказку с запросом шаблона. Я выбрал [hello-world], базовую функцию JavaScript, которая показывает использование async/await и форматирует ваш ответ. Приглашение также запрашивает имя для вашей функции, я назвал свою `webhook`. Вывод моей команды выглядел примерно так:
$ netlify functions:create
? Pick a template js-hello-world
? name your function: webhook
◈ Creating function webhook
◈ Created /Users/laka/fidel/fidel-webhooks-netlify/functions/webhook/hello-worКоманда также создала файл [webhook.js] в папке [/functions/webhook/]. Это был шаблонный код, и я его немного изменил. Я удаляю код [Hello World] и вместо регистрации тела запроса отправляю обратно статус [200 OK] в ответе. Вся логика заключена в [try/catch], который отправляет статус [500] и ошибку в ответе, если что-то случилось с запросом. Чего не должно быть, но лучше перестраховаться, чем потом сожалеть. Большинство API имеют механизм повторных попыток для веб-перехватчиков, поэтому, если мы отправим обратно что-либо, кроме [200], API повторно отправит веб-перехватчик позже.
exports.handler = async (event, context) => {
try {
console.log(event.body)
return {
statusCode: 200
}
} catch (err) {
return { statusCode: 500, body: err.toString() }
}
}Развертывание функции Netlify
Это самый простой пример вебхука, который я мог придумать. Он регистрирует или сохраняет событие, поступающее от API, и отправляет код подтверждения. То, что вы делаете внутри этого веб-перехватчика, должно основываться на логике вашего приложения. Здесь я показываю вам механизм этого транспортного шаблона.
Код необходимо развернуть, прежде чем мы сможем его использовать, поэтому давайте продолжим и воспользуемся для этого интерфейсом командной строки Netlify.
netlify deploy --prodПосле завершения развертывания вывод моего терминала выглядел примерно так:
$ netlify deploy --prod
Deploy path: /Users/laka/fidel/fidel-webhooks-netlify/dist
Functions path: /Users/laka/fidel/fidel-webhooks-netlify/functions
Configuration path: /Users/laka/fidel/fidel-webhooks-netlify/netlify.toml
Deploying to main site URL...
✔ Finished hashing 1 files and 1 functions
✔ CDN requesting 0 files and 1 functions
✔ Finished uploading 1 assets
✔ Deploy is live!
Logs: https://app.netlify.com/sites/fidel-webhooks/deploys/5f19b5e49db36302958eeefe
Unique Deploy URL: https://5f19b5e49db36302958eeefe--fidel-webhooks.netlify.app
Website URL: https://fidel-webhooks.netlify.appКак только развертывание будет запущено, вы сможете получить доступ к журналам веб-перехватчиков в своей панели управления Netlify. Если вы выберете там свой веб-хук, вы увидите, как окно журнала обновляется в режиме реального времени, и именно там вы также найдете конечную точку своей функции. Netlify использует соглашение об именах https://your-app.netlify.app/.netlify/functions/your-function. У меня было https://fidel-webhooks.netlify.app/.netlify/functions/webhook.
Настройка для Fidel API
Ваш веб-хук активен и готов к приему событий, единственное, чего не хватает, — это API для фактической отправки этих событий 😅. Не волнуйтесь, я предоставил вам пример использования Fidel API для отправки событий авторизации транзакций на ваш веб-перехватчик.
Fidel API предоставляет данные о транзакциях в режиме реального времени о покупках, сделанных с помощью карты, выпущенной Visa, Mastercard или Amex. Из-за этого компонента реального времени было бы неразумно опрашивать его каждую секунду или около того, чтобы увидеть, есть ли какие-либо новые транзакции. API реализует механизм веб-перехватчика для отправки этих данных в ваше приложение всякий раз, когда происходит новое событие. На самом деле он поддерживает довольно много веб-перехватчиков для различных типов событий, но я не буду вдаваться в подробности. Сейчас мы просто сосредоточимся на транзакциях.
Прежде чем мы начнем, вам нужно получить свой Ключ Fidel API с панели управления. Я использую для этого свой тестовый ключ, я хочу иметь возможность имитировать транзакции. Он должен быть похож на sk_test_50ea90b6-2a3b-4a56-814d-1bc592ba4d63.
API требует, чтобы вы настроили некоторые каналы, прежде чем вы сможете получать транзакции, и мы собираемся использовать команды cURL для выполнения этой настройки вместо того, чтобы указывать и щелкать на панели инструментов. Если вы уже являетесь пользователем Fidel и зарегистрировали программу, бренд, местоположение и карту, не стесняйтесь пропустить эти шаги — сразу приступайте к регистрации веб-перехватчика в API Fidel.
Контейнером для ваших транзакций в мире Фиделя является Программа. Мы начнем с создания одного. Не забудьте заменить [fidel-key] своим собственным, прежде чем запускать команду cURL.
curl -X POST \
https://api.fidel.uk/v1/programs \
-H 'content-type: application/json' \
-H 'fidel-key: sk_test_50ea90b6-2a3b-4a56-814d-1bc592ba4d63' \
-d '{
"name": "Avocados"
}'Команда выводит ответ JSON от API с данными о созданной нами программе. Мы найдем его «id» и сделаем заметку, мы будем использовать его позже.
{"items":[{"accountId":"3693ac7e-3e2b-432c-8c60-2b786453ca9b","live":false,"name":"Avocados","syncStats":{"status":"completed"},"updated":"2020-07-24T12:03:00.251Z","created":"2020-07-24T12:03:00.251Z","id":"08a09745-1e75-4ac3-baaf-f8548c31b25e","active":true,"activeDate":"2020-07-24T12:03:00.251Z","sync":false}],"resource":"/v1/programs","status":201,"execution":79.233234}Теперь, когда у нас есть программа, нам также нужно создать бренд для нашей программы.
curl -X POST \
https://api.fidel.uk/v1/brands \
-H 'content-type: application/json' \
-H 'fidel-key: sk_test_50ea90b6-2a3b-4a56-814d-1bc592ba4d63' \
-d '{
"name": "Bacon Avocados"
}'Вот вывод этой команды. Мы также запишем [id] для бренда, он нам понадобится позже.
{"items":[{"accountId":"3693ac7e-3e2b-432c-8c60-2b786453ca9b","consent":true,"live":false,"name":"Bacon Avocados","updated":"2020-07-24T12:05:35.868Z","created":"2020-07-24T12:05:35.868Z","id":"59ded730-007e-43a6-8547-7612d31355cb"}],"resource":"/v1/brands","status":201,"execution":15.915342}Теперь, когда у нас есть бренд и программа, мы можем создать местоположение для этого бренда. Это место представляет собой физический магазин, поэтому позже мы можем смоделировать транзакцию в реальном времени, происходящую из него. Мы будем использовать идентификатор программы, полученный из предыдущей команды, и заменим его в URL-адресе. Мы также будем использовать [brandId] в теле запроса, чтобы связать местоположение с брендом [Bacon Avocados].
curl -X POST \
https://api.fidel.uk/v1/programs/08a09745-1e75-4ac3-baaf-f8548c31b25e/locations \
-H 'content-type: application/json' \
-H 'fidel-key: sk_test_50ea90b6-2a3b-4a56-814d-1bc592ba4d63' \
-d '{
"address": "2 Avocado Square",
"brandId": "59ded730-007e-43a6-8547-7612d31355cb",
"city": "London",
"countryCode": "GBR",
"postcode": "W1D 3PX",
"searchBy": {
"merchantIds": {
"visa": ["1234567","7654321"],
"mastercard": ["1234567","7654321"]
}
}
}'Выходные данные для этой команды содержат немного больше данных, потому что в расположении есть информация для каждой доступной сетевой схемы карты. Нам также нужно записать [id], это то, что мы собираемся использовать для идентификации этого местоположения при совершении транзакции.
{"items":[{"accountId":"3693ac7e-3e2b-432c-8c60-2b786453ca9b","address":"2 Avocado Square","brandId":"59ded730-007e-43a6-8547-7612d31355cb","city":"London","countryCode":"GBR","currency":"GBP","live":false,"postcode":"W1D3PX","programId":"08a09745-1e75-4ac3-baaf-f8548c31b25e","geolocation":{"latitude":51.5138332,"longitude":-0.1318224},"preonboard":false,"searchBy":{"merchantIds":{"visa":["1234567","7654321"],"mastercard":["1234567","7654321"]}},"timezone":"Europe/London","updated":"2020-07-24T12:10:17.533Z","created":"2020-07-24T12:10:17.533Z","id":"fe77e7f5-350b-4c34-be68-3e16e7c95d66","amex":{"clearing":false,"auth":false,"authTransactionId":null,"clearingTransactionId":null,"status":"active"},"mastercard":{"clearing":false,"auth":false,"authTransactionId":null,"clearingTransactionId":null,"status":"active"},"visa":{"clearing":false,"auth":false,"authTransactionId":null,"clearingTransactionId":null,"status":"active"},"activeDate":"2020-07-24T12:10:17.533Z","active":true}],"resource":"/v1/programs/08a09745-1e75-4ac3-baaf-f8548c31b25e/locations","status":201,"execution":55.277626}Теперь, когда мы настроили наше местоположение, единственной недостающей частью является карта для имитации транзакции из этого местоположения. Нам также нужно заменить идентификатор программы в URL-адресе. Мы не собираемся регистрировать здесь настоящую карту, мы используем тестовые карты. В зависимости от сети карт, которую мы хотим использовать, мы можем использовать разные диапазоны номеров карт. Например, я буду использовать тестовую карту Visa. Они следуют подстановочному формату в диапазоне [4444 0000 0000 4***]. Я буду использовать [4444000000004001] в качестве номера карты. API карт также использует другой ключ для авторизации, поэтому вместо секретного ключа API вам нужно будет использовать свой публичный ключ SDK из Dashboard. Он похож на другой, главное отличие в том, что он начинается с [pk] вместо [sk]. В моем примере используется [pk_test_62f02030–0409–4eb5-ab94–6eff05b3d888].
curl -X POST \
https://api.fidel.uk/v1/programs/08a09745-1e75-4ac3-baaf-f8548c31b25e/cards \
-H 'content-type: application/json' \
-H 'fidel-key: pk_test_62f02030-0409-4eb5-ab94-6eff05b3d888' \
-d '{
"number": "4444000000004222",
"expMonth": 10,
"expYear": 2025,
"countryCode": "GBR",
"termsOfUse": true
}'Вывод команды должен дать нам идентификатор карты, и мы его запишем. Это то, что нам понадобится, когда мы совершим транзакцию.
{"items":[{"accountId":"3693ac7e-3e2b-432c-8c60-2b786453ca9b","countryCode":"GBR","expDate":"2025-10-31T23:59:59.999Z","expMonth":10,"expYear":2025,"firstNumbers":"444400","lastNumbers":"4222","live":false,"programId":"08a09745-1e75-4ac3-baaf-f8548c31b25e","scheme":"visa","type":"visa","updated":"2020-07-24T12:28:16.957Z","created":"2020-07-24T12:28:16.957Z","id":"bb9b4a67-203c-4eae-8b09-070e819629cc"}],"resource":"/v1/programs/08a09745-1e75-4ac3-baaf-f8548c31b25e/cards","status":201,"execution":47.026675}Зарегистрировать вебхук
Мы настроили все необходимое, чтобы начать получать транзакции через Fidel API. Но пока они будут отображаться только в Fidel Dashboard. Если мы хотим использовать транзакции в реальном времени в нашем приложении, нам нужно зарегистрировать для них URL-адрес веб-перехватчика. Как я упоминал ранее, Fidel API поддерживает несколько различных веб-перехватчиков. Сегодня мы собираемся использовать событие [transaction.auth], которое срабатывает при авторизации транзакции. Обычно это происходит, как только вы используете свою карту лично или в Интернете для совершения покупок. Не забудьте заменить идентификатор программы в URL на свой. И используйте свой собственный URL-адрес веб-перехватчика Netlify в полезной нагрузке запроса.
curl -X POST \
https://api.fidel.uk/v1/programs/08a09745-1e75-4ac3-baaf-f8548c31b25e/hooks \
-H 'content-type: application/json' \
-H 'fidel-key: sk_test_50ea90b6-2a3b-4a56-814d-1bc592ba4d63' \
-d '{
"event": "transaction.auth",
"url": "https://fidel-webhooks.netlify.app/.netlify/functions/webhook"
}'Ответ JSON от API должен быть выведен на терминал. Это выглядит примерно так:
{"items":[{"accountId":"3693ac7e-3e2b-432c-8c60-2b786453ca9b","event":"transaction.auth","live":false,"programId":"08a09745-1e75-4ac3-baaf-f8548c31b25e","url":"https://fidel-webhooks.netlify.app/.netlify/functions/webhook","updated":"2020-07-24T12:39:15.131Z","created":"2020-07-24T12:39:15.131Z","id":"df1ab75a-04f9-4627-9b0a-c08cd28572e5","secretKey":"wh_ta_425e3be6-d7e3-4ad4-b747-5d5c498f171b"}],"resource":"/v1/programs/08a09745-1e75-4ac3-baaf-f8548c31b25e/hooks","status":201,"execution":87.066399}Создать транзакцию аутентификации
Теперь, когда мы зарегистрировали наш веб-хук в Fidel API, мы можем начать создавать тестовые транзакции, и мы должны увидеть их появление в журналах функции Netlify. Мы используем конечную точку тестовых транзакций в Fidel API, и это работает только в тестовом режиме. Если ваша учетная запись активна, вам нужно переключить ее обратно в тестовый режим, чтобы следовать этому руководству. Не забудьте заменить свои [locationId] и [cardId] в полезной нагрузке запроса.
curl -X POST \
https://api.fidel.uk/v1/transactions/test \
-H 'content-type: application/json' \
-H 'fidel-key: sk_test_50ea90b6-2a3b-4a56-814d-1bc592ba4d63' \
-d '{
"amount": 12.34,
"cardId": "bb9b4a67-203c-4eae-8b09-070e819629cc",
"locationId": "fe77e7f5-350b-4c34-be68-3e16e7c95d66"
}'После запуска этой команды вы можете увидеть журналы веб-перехватчиков в журнале функции Netlify. Мой выглядел примерно так после того, как я получил событие на свой вебхук:
1:51:56 PM: 2020-07-24T12:51:56.589Z 7989b0a6-f0ce-4985-a45f-7e22ec0ff6c6 INFO {"auth":true,"currency":"GBP","id":"4b549d95-1540-4332-891a-dd2c7603b090","amount":12.34,"wallet":null,"created":"2020-07-24T12:51:55.918Z","accountId":"36081095-2782-4669-8a07-857bbaaeb89b","cleared":false,"updated":"2020-07-24T12:51:55.918Z","programId":"f2c9719a-6433-4ef4-8401-19d7ebf60ab9","datetime":"2020-07-24T13:51:55","card":{"id":"14bda5c9-d5d9-40ef-87e3-158c2f5f2f8d","firstNumbers":"444400","lastNumbers":"4001","scheme":"visa"},"location":{"address":"Titulescu Nr. 16","city":"Bristol","countryCode":"GBR","id":"793f5298-3715-43ef-b89d-1b1cedddd716","geolocation":null,"postcode":"BS16UZ","timezone":"Europe/London","metadata":null},"brand":{"id":"9cd32c61-43ca-4bb7-8aca-0cf491112c28","name":"Avocado","logoURL":"https://developeravocados.net/img/avatar-icon.png","metadata":null},"identifiers":{"MID":"TEST_MID_a7d6bc8f-7837-4f3b-aa43-8c51478ce189","mastercardTransactionSequenceNumber":null,"mastercardRefNumber":null,"amexApprovalCode":null,"visaAuthCode":null}}
1:51:56 PM: Duration: 1.36 ms Memory Usage: 64 MBЧто дальше?
Надеюсь, вы последовали за мной в этом путешествии, и нам удалось получить события веб-перехватчика в функции Netlify с помощью JavaScript. Если вы нашли их интересными, вы можете сделать с ними гораздо больше вещей. Например, вы можете сохранить это событие транзакции в базе данных FaunaDB.
Если Fidel API вызвал у вас любопытство, и вы хотите продолжить изучение, имейте в виду, что все, что я сегодня сделал с cURL, доступно либо через Fidel Dashboard, либо через наш API.
Вы можете проверить Справочник по API и использовать свой любимый HTTP-клиент, чтобы поиграть с ним.
Зайдите в наш Блог, если хотите подписаться на весь наш контент. Посетите наше Сообщество разработчиков, если у вас есть вопросы об API Fidel и нашей технологии — у нас почти наверняка есть ответы!
