Уебхукове
Получавайте известия за статуса на плащанията в реално време
Уебхуковете позволяват на Cost+ да уведомява вашия сървър в реално време при всяка промяна на статуса на поръчка. Вместо да правите polling на API-то, вие предоставяте URL и Cost+ изпраща HTTP POST заявка към него при всяка актуализация.
Как работят уебхуковете
- Вие посочвате
webhook_urlпри създаване на поръчка или конфигурирате URL за уебхукове по подразбиране на ниво проект. - Когато статусът на поръчката се промени (напр. от
newнаcompleted), Cost+ изпраща POST заявка към вашия URL за уебхукове. - Вашият сървър получава уебхука и след това извиква API-то на Cost+, за да извлече пълните детайли на поръчката.
- Вие актуализирате системата си въз основа на верифицирания статус на поръчката.
Никога не се доверявайте само на данните от уебхука, за да изпълните поръчка. Винаги проверявайте статуса на поръчката, като направите заявка GET /v1/orders/{id}/ след получаване на уебхук. Уебхукът е механизъм за уведомяване, а не източник на истина.
Данни на уебхука
Тялото на уебхука е JSON обект, съдържащ типа на събитието и идентификатора на поръчката:
{
"event": "status_changed",
"order_id": "b9ae6...",
"project_id": "proj_abc123"
}| Поле | Описание |
|---|---|
event | Типът на събитието. В момента status_changed за актуализации на поръчки. |
order_id | Уникалният идентификатор на поръчката, чийто статус се е променил. |
project_id | Проектът, към който принадлежи поръчката. |
Задаване на URL за уебхукове
Можете да зададете URL за уебхукове по два начина:
За отделна поръчка
Включете полето webhook_url при създаване на поръчка:
{
"currency": "EUR",
"amount": 1295,
"webhook_url": "https://www.example.com/webhook"
}По подразбиране за проекта
Конфигурирайте URL за уебхукове по подразбиране в таблото за управление на Cost+ в настройките на проекта. Този URL ще се използва за всички поръчки, които не посочват собствен webhook_url.
Дори ако имате настройка по подразбиране на ниво проект, можете да я замените за отделна поръчка, като включите webhook_url в заявката за създаване на поръчка.
Логика за повторни опити
Ако вашият сървър не отговори с 2xx статус код, Cost+ повтаря доставката на уебхука:
- Максимален брой повторни опити: 10 опита
- Интервал между повторните опити: 2 минути между всеки опит
- Таймаут на първия опит: 4 секунди
- Таймаут на следващите опити: 10 секунди
Ако всичките 10 повторни опита се провалят, уебхукът се маркира като неуспешен. Все пак можете да извлечете статуса на поръчката по всяко време чрез polling на API-то.
Уверете се, че вашата крайна точка за уебхукове отговаря бързо (в рамките на 4 секунди за първия опит). Извършвайте всяка продължителна обработка асинхронно след връщане на отговор 200 OK.
Добри практики
- Винаги проверявайте чрез API-то. При получаване на уебхук извикайте
GET /v1/orders/\{order_id\}/, за да потвърдите текущия статус, преди да предприемете действие като изпращане на стоки или предоставяне на достъп. - Връщайте 200 бързо. Потвърдете уебхука с отговор
200незабавно и обработвайте поръчката асинхронно, за да избегнете таймаути. - Обработвайте дубликати. Вашата крайна точка за уебхукове може да получи едно и също събитие повече от веднъж. Уверете се, че логиката за обработка е идемпотентна.
- Използвайте HTTPS. Винаги използвайте HTTPS URL за крайната си точка за уебхукове, за да осигурите сигурно предаване на данните.
- Записвайте данните от уебхуковете. Съхранявайте входящите данни от уебхукове за целите на отстраняване на грешки и одит.
Свързани крайни точки
- Създаване на поръчка — задайте
webhook_urlза всяка поръчка - Актуализиране на поръчка — актуализирайте URL за уебхукове на съществуваща поръчка
- Схеми на събития за уебхукове — формат на данните за
OrderStatusChangedEventиTransactionStatusChangedEvent