Siirry pääsisältöön
Webhookit antavat AgencyHandyn lähettää tietoja ulkoisiin järjestelmiisi heti, kun jokin muuttuu — ilman kyselyä. Kun määritetty tapahtuma laukeaa (esimerkiksi tilaus päivitetään tai tukipyyntö luodaan), AgencyHandy lähettää HTTP POST -pyynnön JSON-hyötykuormalla määrittämääsi päätepiste-URL-osoitteeseen. Tämä tekee helpoksi pitää ulkoiset työkalut, kuten CRM-järjestelmät, laskutusjärjestelmät tai mukautetut dashboardit, synkronoituina AgencyHandy-työtilasi kanssa reaaliajassa.
Business Pro -suunnitelman työtilat tukevat enintään 30 000 webhook-tapahtumaa laskutuskautta kohden. Tarkista suunnitelmasi rajoitukset ennen suurivolyymisten automaatioiden käyttöönottoa.

​
Tuetut tapahtumat

Voit tilata webhookin mihin tahansa yhdistelmään seuraavista tapahtumista:
KategoriaTapahtumat
PalveluLuotu, päivitetty, poistettu
TilausLuotu, päivitetty, poistettu
TehtäväLuotu, osoitettu, suoritettu, päivitetty
LaskuTila muuttunut
Asiakas / KäyttäjäUusi asiakas lisätty, asiakas/käyttäjä poistettu
EhdotusLähetetty, vastaanotettu, hyväksytty, hylätty
TukipyyntöLuotu, osoitettu, tila muuttunut
MaksuVastaanotettu, epäonnistunut
PalvelupakettiLuotu, päivitetty, poistettu

​
Luo webhook

1

Siirry Webhook-hallintaan

Siirry vasemmassa sivupalkissa kohtaan Integrations → Webhooks Management.
2

Todenna tunnuksesi

Napsauta Management-painiketta todentaaksesi webhook-tunnuksesi. Tätä tunnusta käytetään lähtevien hyötykuormien allekirjoittamiseen, jotta voit varmistaa niiden olevan peräisin AgencyHandysta.
3

Luo uusi webhook

Napsauta Create New Webhook avataksesi webhook-määrityslomakkeen.
4

Syötä päätepiste-URL

Syötä Endpoint URL -kenttään ulkoisen järjestelmän URL-osoite, jonka tulee vastaanottaa webhook-tiedot. Tämän on oltava julkisesti saavutettava POST-päätepiste.
5

Valitse sisältötyyppi

Valitse sisältötyypiksi JSON. AgencyHandy lähettää kaikki webhook-hyötykuormat muodossa application/json.
6

Valitse webhook-tapahtumat

Valitse kaikki tapahtumat, joiden tulee käynnistää tämä webhook. Voit valita tapahtumia useista kategorioista — esimerkiksi Order: Created ja Invoice: Status changed voivat molemmat osoittaa samaan päätepisteeseen.
7

Aktivoi webhook

Vaihda Active-valintanappula päälle. Kun webhook on aktiivinen, AgencyHandy toimittaa hyötykuormat kaikista valituista tapahtumista päätepisteellesi reaaliajassa.
8

Tallenna määritys

Tarkista asetuksesi ja napsauta Save. Webhook näkyy luettelossa ja alkaa toimittaa tapahtumia välittömästi.

​
Testaa webhook

Webhookin luomisen jälkeen lähetä testitiedot vahvistaaksesi, että päätepisteesi on saavutettavissa ja käsittelee tietoja oikein.
1

Avaa webhook

Napsauta Webhooks Management -luettelossa webhookia, jonka haluat testata.
2

Napsauta Test Event

Napsauta Test Event -painiketta webhookin tietosivulla.
3

Valitse testitapahtuma

Valitse esimerkkitapahtuma webhookin määritettyjen tapahtumien luettelosta (esim. Order: Created).
4

Lähetä testitiedot

Napsauta Send. AgencyHandy lähettää esimerkkihyötykuorman päätepiste-URL-osoitteeseesi.
5

Tarkista tulos

Tarkista ulkoisesta järjestelmästäsi, että testitiedot saapuivat ja käsiteltiin odotetusti. Napsauta takaisin AgencyHandyssa webhookiin tarkastellaksesi sen historiaa — näet koko pyynnön, päätepisteesi palauttaman vastauksen ja voit toimittaa uudelleen minkä tahansa aiemman tapahtuman tarvittaessa.
Käytä työkalua kuten Webhook.site tai RequestBin väliaikaisena päätepisteenä asennuksen aikana tarkistaaksesi tarkan hyötykuorman rakenteen ennen todellisen järjestelmän kytkemistä.

​
Todenna webhook-hyötykuormat

Jokainen AgencyHandyn lähtevä webhook-pyyntö sisältää allekirjoitusotsikon, jota päätepisteesi voi käyttää varmistaakseen, että hyötykuorma on aito eikä sitä ole peukaloitu.

​
Allekirjoitusotsikko

x-ah-sig: <signature>
AgencyHandy lisää tämän otsikon jokaiseen webhook-pyyntöön. Pura arvo saapuvista pyynnöistä ja välitä se vahvistuspäätepisteelle.

​
Todenna webhook-allekirjoitus

Lähetä seuraava pyyntö vahvistaaksesi, että hyötykuorma on aito: 
POST https://api.agencyhandy.com/api/v1/webhooks/verify-signature
Content-Type: application/json
​
webhookId
string
vaadittu
Sen webhookin tunnus, joka vastaanotti tapahtuman. Löydät tämän webhookin tietosivulta AgencyHandyssa.
​
signature
string
vaadittu
Saapuvan webhook-pyynnön x-ah-sig-otsikon arvo.
​
secret
string
vaadittu
Webhookin tietosivulla AgencyHandyssa näkyvä webhook-salaisuus.
​
payload
object
vaadittu
AgencyHandyn webhook-pyynnöstä vastaanotettu raaka JSON-runko.
const url = 'https://api.agencyhandy.com/api/v1/webhooks/verify-signature';

const postData = {
  webhookId: 'your_webhook_id',
  signature: 'your_signature',   // value of x-ah-sig header
  secret: 'your_webhook_secret',
  payload: {},                   // the parsed JSON body from AgencyHandy
};

const response = await fetch(url, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(postData),
});

const data = await response.json();
console.log(data); // { "verification_status": "SUCCESS" }
Vastaukset
​
verification_status
string
SUCCESS kun allekirjoitus on kelvollinen. FAILED kun vahvistus epäonnistuu (HTTP 403).
Success (200)
{
  "verification_status": "SUCCESS"
}
Failure (403)
{
  "type": "PermissionError",
  "status": 403,
  "verification_status": "FAILED"
}
Pidä webhook-salaisuutesi luottamuksellisena. Kierrä sitä säännöllisesti ja päivitä vahvistuslogiikkasi välittömästi kierron jälkeen. Älä koskaan paljasta sitä asiakaspuolen koodissa tai julkisissa repositorioissa.

​
Tärkeät huomiot

  • Päätepiste-URL-osoitteesi on oltava julkisesti saavutettava HTTPS POST -URL.
  • Jos päätepisteesi on tilapäisesti poissa käytöstä, tarkista webhookin historiaruutu AgencyHandyssa — voit toimittaa uudelleen minkä tahansa aiemman tapahtuman suoraan sieltä.
  • Seuraa säännöllisesti webhook-toimintaa havaitaksesi epäonnistuneet toimitukset tai luvattomat käyttöyritykset.
  • Toistuvasti epäonnistuvat webhookit voidaan keskeyttää AgencyHandyn toimesta — tarkista toimituslokit ongelmien havaitsemiseksi ajoissa.