Пересилання

Задайте bin-у URL пересилання — і кожен записаний ним запит також надсилатиметься далі на ваш власний сервер у тому вигляді, у якому надійшов. Відправник, як і раніше, одразу отримує 200 від bin-а. Bin сам надсилає запит далі, пробує знову, коли ваш сервер дає збій, і зберігає відповідь вашого сервера поруч із запитом, тож в одному місці видно, що надіслав відправник і що з цим зробив ваш ендпоінт.

Хто може пересилати і куди

Пересилання доступне на Starter, Pro і Custom. На Free спроба задати URL пересилання отримує відповідь 402 not_entitled з details.feature forwarding.

Bin пересилає на один URL, і цей URL має бути:

• https, з будь-яким портом. Сертифікат перевіряється на відповідність імені хоста з URL.
• Без імені користувача чи пароля.
• У публічному інтернеті. Кожна адреса, у яку розвʼязується його хост, має бути публічною: приватна, loopback, link-local чи інша зарезервована адреса відхиляється, як і хост, який не розвʼязується.
• Не нашим. nnbin.net, nimbusnexus.net і всі імена під ними відхиляються, як і будь-яке імʼя, що розвʼязується в одну з наших власних адрес: bin не може пересилати в bin або у власні сервіси NimbusNexus.
• Не довшим за 2 048 символів.

URL перевіряється, коли ви його задаєте, і знову перед кожним надсиланням, а кожне надсилання йде лише на адреси, які знайшла ця перевірка, тож зміна DNS тим часом не може спрямувати його деінде. Переспрямування не виконуються: відповідь 3xx зберігається як відповідь вашого сервера, і пересилання вважається надісланим, бо переспрямування могло б вести на будь-яку адресу, якої перевірка ніколи не бачила.

До URL пересилання додаються шлях і query кожного запиту. Якщо URL пересилання — https://api.example.com/hooks, запит на https://nnbin.net/b/k7xq2mbn9tfa/stripe/events?x=1 іде на https://api.example.com/hooks/stripe/events?x=1. Запит на URL bin-а без шляху йде на URL пересилання в тому вигляді, у якому ви його задали, а рядок query, який містить сам URL пересилання, іде першим.

Задайте URL кнопкою Set up forwarding на картці Forwarding bin-а в консолі або через forward_url у PATCH /v1/bins/{id}:

curl -X PATCH https://bins.nimbusnexus.net/v1/bins/bin_3f9a1c7e5b2d8f4a6c0e9b17 \
  -H "Authorization: Bearer $BINS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"forward_url": "https://api.example.com/hooks"}'

У відповідь повертається bin із заданим forward_url. Stop forwarding на картці або "forward_url": null вимикає пересилання. Щоб задати URL, потрібна роль учасника або ключ із Read & write. URL, що порушує одне з правил вище, відхиляється з 422, а кожну причину перелічено в довіднику.

Попередня перевірка URL

Send a test на картці Forwarding або POST /v1/bins/{id}/forward-test одразу надсилає вашому серверу невелику подію JSON і показує, що він відповів, тож ви знатимете, що URL працює, ще до того, як від нього залежатиме справжній трафік:

curl -X POST https://bins.nimbusnexus.net/v1/bins/bin_3f9a1c7e5b2d8f4a6c0e9b17/forward-test \
  -H "Authorization: Bearer $BINS_API_KEY"

{
  "ok": true,
  "answer": {
    "status": 200,
    "headers": [
      {"name": "content-type", "value": "text/plain"}
    ],
    "body_base64": "b2s=",
    "truncated": false
  },
  "duration_ms": 142,
  "error": ""
}

Ваш сервер отримує POST із тілом {"type":"request_bins.forward_test","bin":"<slug>","sent_at":"<when>"}, з Content-Type: application/json, User-Agent: NimbusNexus-Request-Bins (forward test), X-Request-Bins-Request: test, а також Via і X-Forwarded-Host, які має кожне пересилання. ok дорівнює true для відповіді 2xx або 3xx. Коли відповіді немає, answer дорівнює null, а error пояснює причину, як-от тайм-аут. Bin може надсилати 10 тестів на хвилину.

Що надсилається

Пересилання — це запит у тому вигляді, у якому його записав bin:

• метод, хоч би який він був;
• тіло, байт у байт;
• заголовки в порядку надходження, крім наведених нижче, а після них — наші.

Відкидаються, бо стосуються одного зʼєднання чи одного хопу, а не запиту: Connection і кожен заголовок, який він називає, Keep-Alive, Proxy-Connection, Proxy-Authenticate, TE, Trailer, Transfer-Encoding і Upgrade; Host, який стає хостом вашого сервера, і Content-Length, який обчислюється заново; а також X-Real-IP, X-Forwarded-Proto, X-Forwarded-Host, CDN-Loop і кожен заголовок CF-*, які описують попередній хоп; пересилання задає власні X-Forwarded-Proto і X-Forwarded-Host. Власний X-Request-Bins-Request відправника теж відкидається, тож ваш сервер читає саме наш.

Не пересилаються: облікові дані. Authorization, Proxy-Authorization, Cookie, Set-Cookie і X-Api-Key ніколи не виходять за межі bin-а. URL bin-а публічний, тож bin замінює ці значення на [redacted] ще до того, як щось буде збережено, і нічого з того, що відправник у них поклав, не зберігається — навіть на ту мить, коли це знадобилося б пересиланню. Заголовки підпису, як-от Stripe-Signature чи X-Hub-Signature-256, не є обліковими даними й пересилаються. Тіло не змінюється, тож підписи й далі проходять перевірку, хоча повторна спроба може надійти вже після того, як сплив допуск для підпису з timestamp. Ціна цього: сервер, який автентифікує свого клієнта за одним із цих пʼяти заголовків, відхиляє переслані запити.

Додаються після заголовків відправника:

Доставка й повтори

Відправник одразу отримує 200 і {"status":"accepted"}, як від будь-якого bin-а, хоч би що робив ваш сервер, і ніколи не бачить відповіді вашого сервера. Bin надсилає пересилання сам, зазвичай за кілька секунд після того, як записав запит.

Спроба завершується тайм-аутом, якщо ваш сервер приймає зʼєднання довше за 10 секунд або відповідає довше за 10 секунд. Що буде далі, залежить від того, чим завершилася спроба:

Невдала спроба повторюється через 30 секунд, а далі — через 2 хвилини, 10 хвилин і 30 хвилин після кожної наступної спроби, доки не вичерпано спроби плану: 3 на Starter, тож остання настає приблизно через дві з половиною хвилини після першої, і 5 на Pro та Custom — приблизно через 43 хвилини. Коли відповідь 408, 429 або 5xx містить Retry-After із проханням чекати довше, bin натомість чекає стільки, але не більше години.

Перед кожною спробою bin знову перевіряє, чи може надсилати. Пересилання відкидається як непереслане, щойно bin видалено чи призупинено, пересилання зупинено чи поставлено на паузу, робочий простір призупинено або план більше не включає пересилання. Пересилання йде на URL, заданий на момент надходження його запиту, тож зміна URL не переносить пересилань, які вже чекають.

Надсилаються лише запити, що надходять, поки bin пересилає: увімкнення пересилання не надсилає нічого з того, що bin записав раніше. Кожен запит пересилається окремо, тож запит, надісланий двічі, двічі записується й двічі пересилається. Порядок запитів не зберігається: запит, який надсилається повторно, може дійти до вашого сервера після запиту, що надійшов пізніше.

Як побачити, що сталося

У консолі відкрийте запит. Його розділ Forwarding показує, куди він пішов і в якому він стані (Queued, Sending, Sent, Retrying, Failed або Not forwarded із причиною), зроблені досі спроби, останню помилку й відповідь вашого сервера: її статус, заголовки й перші 8 KiB тіла. Картка Forwarding bin-а показує останнє невдале надсилання.

Через API GET /v1/requests/{id} перелічує пересилання запиту в forwards, найновіші першими. Одне з них:

{
  "id": "fwd_5a1e8c3b7d2f9a4e6c0b1d83",
  "state": "sent",
  "reason": "",
  "url": "https://api.example.com/hooks/orders?source=quickstart",
  "attempts": 1,
  "max_attempts": 3,
  "next_attempt_at": null,
  "last_error": "",
  "answer": {
    "status": 200,
    "headers": [
      {"name": "content-type", "value": "application/json"}
    ],
    "body_base64": "eyJyZWNlaXZlZCI6dHJ1ZX0=",
    "truncated": false
  },
  "duration_ms": 142,
  "created_at": "2026-10-26T09:12:04Z",
  "sent_at": "2026-10-26T09:12:05Z"
}

Усі поля, стани й причини описано в довіднику. Відповідь вашого сервера зберігається стільки ж, скільки й запит, і видаляється разом із ним. Для bin-а forward_last_error і forward_last_error_at показують, що пішло не так з останнім невдалим надсиланням, як-от HTTP 503 або тайм-аут, і ніколи — що містив запит.

Ліміти

• Більше тіло записується, але не пересилається, з причиною body_too_large. Так само й тіло понад 1 MiB на будь-якому плані, бо bin зберігає лише його перший 1 MiB (Що записує bin).
• Понад ліміт пересилань bin-а на хвилину пересилання чекають своєї черги. Через це жодне з них не відкидається.
• Bin тримає щонайбільше 1 000 незавершених пересилань: у черзі, у процесі надсилання або в очікуванні повторної спроби. Запит, що надходить, коли їх стільки, записується, але не пересилається, з причиною queue_full.
• URL пересилання з доданими шляхом і query запиту має вміщатися у 8 192 символи, інакше запит не пересилається (url_too_long).
• Пересилання не витрачає власних запитів. Пересланий запит зараховується до місячного обсягу запитів один раз, коли його записано, а його спроби не зараховуються. Запит, який bin не записав, бо місячний обсяг запитів вичерпано або bin призупинено, також не пересилається.

Коли пересилання стає на паузу

Коли ваш сервер раз у раз дає збій, bin перестає на нього надсилати: пересилання стає на паузу після 20 невдалих спроб поспіль або після години, протягом якої всі спроби були невдалими. Одна успішна спроба скидає обидва лічильники.

Поки пересилання на паузі, bin і далі записує, але нічого не надсилає: кожен запит, що надходить, і кожне пересилання, що чекало, позначаються як непереслані з причиною paused, і жодне з них не буде надіслано пізніше. Bin показує, коли й чому пересилання стало на паузу: Paused на його картці Forwarding, а в API — forward_paused_at і forward_paused_reason (failed_in_a_row або failing_for_an_hour).

Робочий простір отримує сповіщення — один раз за кожну паузу, так само, як і про місячний обсяг запитів: листом, що надходить власнику робочого простору, якщо ви не виберете іншу адресу, і вебхуком, якщо ви його налаштували. Обидва налаштовуються в розділі Notifications у консолі акаунта. Відновлення нічого не надсилає.

Лист «Request Bins: forwarding was paused on one of your bins» називає bin за його міткою та URL, а також хост, на який він пересилав, але ніколи — шлях чи query. У ньому сказано, чому пересилання стало на паузу, із зазначенням останньої помилки, а також що запити й далі записуються, але жоден не пересилається, тож записані тим часом запити не буде переслано пізніше. Наприкінці — як відновити пересилання.

Тип події вебхука — bind.forwarding.paused, а його тіло таке:

{
  "type": "bind.forwarding.paused",
  "workspace_id": "<workspace-id>",
  "data": {
    "bin_id": "bin_3f9a1c7e5b2d8f4a6c0e9b17",
    "label": "Quickstart",
    "url": "https://nnbin.net/b/w4tz8hcv2qnd",
    "forward_host": "api.example.com",
    "reason": "failed_in_a_row",
    "paused_at": "2026-10-26T14:05:12.345678Z",
    "failures": 20,
    "last_error": "HTTP 503"
  }
}

reason дорівнює failed_in_a_row або failing_for_an_hour, failures — скільки надсилань поспіль були невдалими, а last_error — що пішло не так з останнім із них. forward_host — лише хост URL пересилання: сповіщення ніколи не містить шляху чи query цього URL, у яких може бути секрет.

Щоб відновити пересилання, коли ваш сервер полагоджено, виберіть Resume на картці Forwarding або знову задайте forward_url через PATCH /v1/bins/{id} — той самий URL чи новий. Пересилання знову починається з наступного запиту, який запише bin, а Send a test покаже, чи відповідає ваш сервер.

Звідки надходять пересилання

Пересилання й тестові надсилання надходять на ваш сервер з 23.247.240.155 через IPv4, тож сервер, хост якого має лише IPv6-адреси, не може їх отримати. Це адреса на сьогодні, і вона може змінитися: ця сторінка повідомить про це заздалегідь. Якщо ваш сервер приймає запити лише з відомих йому адрес, дозвольте цю адресу.

Чим пересилання не є

• Проксі. Відправник отримує 200 від bin-а й ніколи — відповідь вашого сервера, а bin не може відповісти статусом, заголовками чи тілом на ваш вибір.
• Реплей. Записаний запит не можна надіслати знову на вимогу: кожен пересилається один раз, щойно надходить, разом зі своїми повторними спробами.
• Розгалуження. Bin пересилає на один URL. Щоб перевіряти підписи провайдера й доставляти його вебхуки на кілька ваших ендпоінтів, з dead-letter чергою та повторною доставкою, використовуйте джерело Webhooks.

Що далі

• Довідник Request Bins — forward_url, тестове надсилання й усі поля пересилання.
• Огляд продукту — що записує bin і ліміти кожного плану.
• Джерела Webhooks — вебхуки провайдера, перевірені й доставлені на ваші ендпоінти.