Webhooks

Добивајте потпишано HTTPS барање на ваша адреса секогаш кога ќе се промени клиент, документ, плаќање, трошок, статус во е-Фактура или договор.

4 мин. читање Ажурирано 04.10.2026 Потребно: REST API и webhooks

Webhook адресата е URL на вашиот сервер што Bilify го повикува кога нешто ќе се случи во работниот простор, на пример кога ќе се издаде фактура или ќе се потпише договор. Вашиот систем реагира веднаш, наместо на неколку минути да го прашува API.

Адресите се управуваат во Поставки > Интеграции, во делот Webhooks. Сопственикот и администраторите можат да ги додаваат и менуваат.

Додавање адреса

Интерактивен преглед Додајте webhook адреса Чекор 1 од 9
Чекор 1: Адреси ги прикажува URL адресите што добиваат настани од овој работен простор, со околина и статус. Чекор 2: Додај адреса го отвора формуларот. Чекор 3: Внесете јавна https адреса на вашиот сервер. Приватни и localhost адреси се одбиваат. Чекор 4: Штиклирајте ги настаните што ви требаат, или Сите настани за да добивате сè. Чекор 5: Тука се претплатуваме и на целосно потпишани договори. Чекор 6: Описот е незадолжителен и помага да ги разликувате адресите. Чекор 7: Зачувај ја додава адресата и создава таен клуч за потпишување. Чекор 8: Копирајте го тајниот клуч сега. Вашиот сервер го користи за проверка на заглавието X-Bilify-Signature. Чекор 9: Готово го затвора прозорецот. Испораките ќе се гледаат под Неодамнешни испораки.

Адреси ги прикажува URL адресите што добиваат настани од овој работен простор, со околина и статус.

Додај адреса го отвора формуларот.

Внесете јавна https адреса на вашиот сервер. Приватни и localhost адреси се одбиваат.

Штиклирајте ги настаните што ви требаат, или Сите настани за да добивате сè.

Тука се претплатуваме и на целосно потпишани договори.

Описот е незадолжителен и помага да ги разликувате адресите.

Зачувај ја додава адресата и создава таен клуч за потпишување.

Копирајте го тајниот клуч сега. Вашиот сервер го користи за проверка на заглавието X-Bilify-Signature.

Готово го затвора прозорецот. Испораките ќе се гледаат под Неодамнешни испораки.

  1. Чекор 1: Адреси ги прикажува URL адресите што добиваат настани од овој работен простор, со околина и статус.
  2. Чекор 2: Додај адреса го отвора формуларот.
  3. Чекор 3: Внесете јавна https адреса на вашиот сервер. Приватни и localhost адреси се одбиваат.
  4. Чекор 4: Штиклирајте ги настаните што ви требаат, или Сите настани за да добивате сè.
  5. Чекор 5: Тука се претплатуваме и на целосно потпишани договори.
  6. Чекор 6: Описот е незадолжителен и помага да ги разликувате адресите.
  7. Чекор 7: Зачувај ја додава адресата и создава таен клуч за потпишување.
  8. Чекор 8: Копирајте го тајниот клуч сега. Вашиот сервер го користи за проверка на заглавието X-Bilify-Signature.
  9. Чекор 9: Готово го затвора прозорецот. Испораките ќе се гледаат под Неодамнешни испораки.
  1. Отворете Поставки > Интеграции и одете до Webhooks.
  2. Во картичката Адреси кликнете Додај адреса.
  3. Внесете URL адреса. Мора да биде јавна https:// адреса. Приватни, localhost и резервирани адреси се одбиваат.
  4. Под Настани штиклирајте ги настаните што ви требаат, или Сите настани за да добивате сè, вклучувајќи и настани што ќе се додадат во иднина.
  5. По желба внесете Опис, на пример „Сметководствена синхронизација“.
  6. Оставете Активна вклучено и кликнете Зачувај.
  7. Копирајте го Тајниот клуч за потпишување (почнува со whsec_), зачувајте го во поставките на вашиот примач, па кликнете Готово. Ви треба за проверка на потписите.

Тајниот клуч се прикажува само еднаш

Ако го изгубите, отворете го менито на адресата и изберете Генерирај нов клуч. Стариот клуч веднаш престанува да важи, па ажурирајте го примачот во истиот момент.

Околина во формуларот не е избор. Адресите што ги додавате во продукцискиот работен простор добиваат само продукциски настани. За настани од тест околината, отворете ја тест околината и додадете ја адресата таму (видете Тест околина).

Настани

Настан Кога се праќа
client.created, client.updated Клиент е додаден или изменет
document.created Креиран е документ (нацрт)
document.issued Документот е издаден и добил број
document.updated Секоја друга промена на документ, на пример измена на нацрт, испраќање или сторнирање
document.deleted Избришан е нацрт
payment.recorded Евидентирано е плаќање на документ (data е документот, со новиот платен износ)
expense.created, expense.updated, expense.deleted Трошок е додаден, изменет или избришан (вклучувајќи и автоматски создадени повторливи трошоци)
document.efaktura.sent е-Фактура: документот е евидентиран во УЈП
document.efaktura.accepted е-Фактура: купувачот го прифатил (или е прифатен автоматски)
document.efaktura.rejected е-Фактура: купувачот го одбил
document.efaktura.voided е-Фактура: сторно
document.efaktura.corrected е-Фактура: корегиран
document.efaktura.failed е-Фактура: поднесувањето не успеа
contract.sent Договорот е испратен за потпис
contract.signer_signed Еден потписник потпишал, другите уште чекаат
contract.signed Потпишал последниот потписник
contract.declined Потписник одбил
contract.expired Рокот за потпишување поминал
contract.voided Договорот е поништен

Настаните се праќаат без разлика каде е направена промената: во апликацијата, преку REST API, од AI конекторот или од закажана задача. Настаните за е-Фактура постојат само кај македонски работни простори што ја користат е-Фактура.

Како изгледа испораката

Bilify праќа POST со JSON содржина и овие заглавија:

Content-Type: application/json
User-Agent: Bilify-Webhooks/1
X-Bilify-Signature: t=1791100800,v1=5f2c...

{
  "event": "document.issued",
  "occurred_at": "2026-10-04T09:15:02+02:00",
  "environment": "production",
  "data": { "reference": "01JA0...", "number": "...", "status": "issued", "...": "..." }
}

data го содржи записот во истиот облик во кој го враќа REST API. environment е production или sandbox.

Одговор, повторни обиди и автоматско исклучување

  • Одговорете со кој било статус 2xx во рок од 15 секунди. Сè друго, истечено време или грешка при поврзување се смета за неуспешен обид.
  • По неуспех Bilify повторно се обидува по околу 1 минута, 5 минути, 30 минути, 2 часа, 8 часа и 24 часа. Тоа се вкупно 7 обиди за приближно ден и половина. Потоа испораката добива статус Трајно неуспешно.
  • Ако 5 испораки по ред завршат како Трајно неуспешно, адресата се исклучува автоматски, а сопственикот и администраторите добиваат известување во апликацијата (ѕвонче). Секоја успешна испорака го враќа бројачот на нула. Кај адресата стои забелешка дека е оневозможена поради повеќекратни неуспеси. Вклучете ја повторно со прекинувачот штом серверот пак е достапен.

Примачот нека биде идемпотентен

Поради повторните обиди и копчето Повторно испорачај, истиот настан може да стигне повеќе пати, а настаните може да стигнат и по различен редослед. Испораките немаат посебен id на настанот, па отстранувајте дупликати според комбинацијата event, data.reference и occurred_at, а бавната работа правете ја откако ќе одговорите.

Неодамнешни испораки и повторна испорака

Картичката Неодамнешни испораки ги прикажува последните 30 испораки со Настан, URL на адресата, Статус (Во тек, Испорачано, Неуспешно, Трајно неуспешно), HTTP Код што го вратил вашиот сервер (или Без одговор), Обиди и Креирано.

Кликнете Повторно испорачај во редот за веднаш да ја пратите повторно. Бројачот на обиди почнува од нула, се праќа истата оригинална содржина, потпишана со тековниот таен клуч на адресата и со нов временски печат. Повторна испорака може да побарате и преку API со POST /api/v1/webhook-deliveries/{reference}/redeliver.

Bilify моментално не ги брише старите записи за испораки, така што историјата ви останува достапна за проверки.

Измена, пауза или отстранување на адреса

Во редот на адресата:

  • Прекинувачот ја менува адресата меѓу активна и неактивна. Неактивните адреси не добиваат ништо; настаните што ќе се случат во меѓувреме не се чуваат за подоцна.
  • Менито (трите точки) ги има Измени (URL, настани, опис, активна), Генерирај нов клуч и Отстрани.
  • Отстрани ги запира сите испораки до таа адреса. Историјата на претходните испораки се задржува.

Тестирајте пред да почнете

Користете ја тест околината: додадете адреса внатре во тест околината, креирајте тест податоци таму и гледајте како пристигаат испораки со "environment": "sandbox". Видете Тест околина.

Дали ви помогна оваа страница?

Поврзани статии

Проверка на потписите на webhooks Проверувајте го заглавието X-Bilify-Signature за вашата адреса да прифаќа само вистински и свежи испораки. Готов код за PHP, Node.js и Python. Брз почеток со REST API Направете ги првите повици до Bilify REST API, излистајте клиенти и креирајте нацрт фактура, и научете ги правилата за пристап, лимити, повторувања и грешки. Тест околина Посебна тест копија на вашиот работен простор со свои податоци, тест API клучеви и webhooks, каде е-пошта никогаш не се праќа, а е-Фактура работи во симулатор.

Сè уште имате проблем?

Пишете ни и ќе ви одговориме во рок од еден работен ден.

Контактирајте нè