Черга Webhook Callback

Асинхронний режим MirApi розвантажує API-виклики до фонового пулу воркерів, повертаючи негайний 202 Accepted вашому додатку. Коли upstream відповідає, MirApi надсилає результат POST-запитом на вашу callback URL. Воркер підтримує повну логіку повторів і може повторювати протягом годин при тимчасових збоях.

Як це працює

Ваш Додаток            MirApi                  Upstream API
    |                     |                          |
    |──POST (+X-Webhook)─→|                          |
    |←──202 Accepted──────|                          |
    |   {"job_id": "..."} |                          |
    |                     |──push до Redis queue─→   |
    |                     |                     (async воркер)
    |                     |←──відповідь upstream──────|
    |←──POST /your/webhook|                          |
    |   (повна відповідь) |

Базове використання

curl -X POST https://proxy.mirapi.io/ \
  -H "X-MirApi-Key: $MIRAPI_KEY" \
  -H "X-Target-URL: https://api.stripe.com/v1/charges" \
  -H "X-Identity-Key: Bearer sk_live_..." \
  -H "X-Webhook-Callback: https://your-app.com/api/webhooks/payments" \
  -H "X-Proxy-Idempotency-Key: order_789_pay_attempt_1" \
  -H "Content-Type: application/json" \
  -d '{"amount": 9900, "currency": "usd", "source": "tok_visa"}'

Негайна відповідь:

HTTP/1.1 202 Accepted
Content-Type: application/json

{
  "status": "Accepted",
  "job_id": "8fd2a023-df21-4ea7-8b01-5d9f0f9b36ea"
}

Що отримує ваш callback

При успіху — тіло upstream відповіді:

{
  "id": "ch_3Pz9...",
  "status": "succeeded",
  "amount": 9900,
  "currency": "usd"
}

При збої (всі повтори вичерпані) — помилка:

{
  "error": "upstream_failed",
  "job_id": "8fd2a023-df21-4ea7-8b01-5d9f0f9b36ea",
  "status_code": 503,
  "message": "All retry attempts failed for https://api.stripe.com/v1/charges"
}

З логікою повторів

# Платіж з 5 повторами, починаючи з 1 секунди
curl -X POST https://proxy.mirapi.io/ \
  -H "X-MirApi-Key: $MIRAPI_KEY" \
  -H "X-Target-URL: https://api.stripe.com/v1/charges" \
  -H "X-Identity-Key: Bearer sk_live_..." \
  -H "X-Webhook-Callback: https://your-app.com/payments/done" \
  -H "X-Proxy-Idempotency-Key: order_789_pay_1" \
  -H "X-Retry-Count: 5" \
  -H "X-Retry-Delay: 1s" \
  -H "X-Proxy-Timeout: 10s" \
  -d '{"amount": 9900, "currency": "usd", "source": "tok_visa"}'

Idempotency для async завдань

Завжди використовуйте X-Proxy-Idempotency-Key при async обробці платежів. Якщо той самий ключ надходить знову протягом 60 секунд — MirApi повертає ту саму відповідь 202 з тим самим job_id, без створення дублікату завдання.

Порада

Для безпеки webhook callback перевіряйте, що запит на вашу callback URL надходить від MirApi, через мережевий фаєрвол або перевірку відомих IP-адрес MirApi.

Практичний приклад: Платіжний потік e-commerce

# Крок 1: Надіслати async платіж
curl -X POST https://proxy.mirapi.io/ \
  -H "X-MirApi-Key: $MIRAPI_KEY" \
  -H "X-Target-URL: https://api.stripe.com/v1/charges" \
  -H "X-Identity-Key: Bearer sk_live_..." \
  -H "X-Webhook-Callback: https://myshop.com/api/payments/confirm" \
  -H "X-Proxy-Idempotency-Key: order_456_cart_789_attempt_1" \
  -H "X-Retry-Count: 3" \
  -H "X-Proxy-Timeout: 15s" \
  -H "Content-Type: application/json" \
  -d '{"amount": 25000, "currency": "usd", "source": "tok_visa"}'

# Крок 2: Ваш додаток відразу відповідає користувачу ("Обробляємо платіж...")
# Крок 3: Воркер MirApi дзвонить Stripe, повторює при потребі
# Крок 4: Stripe успішний → MirApi POST на /api/payments/confirm
# Крок 5: Ваш обробник позначає замовлення як оплачене