Webhookit
Webhookien avulla voit pitää työntekijätiedot synkronoituina Human ja minkä tahansa yhdistämäsi ulkoisen palvelun tai alustan välillä.
Sisällysluettelo
- Roolit ja käyttöoikeudet
- Useat integraatiot
- Tuetut ominaisuudet
- Voinko käyttää webhookeja palvelulle "X"?
- Näin määrität webhookin
- Profiilin sähköpostiosoitteen muutostapahtuma
- Profiilitapahtumat
- Profiilitapahtumien tuetut kentät
- Yrityskohtaiset kentät
- Tehtävätapahtumat
- Tehtävätapahtumien tuetut kentät
- Poissaolotapahtumat
- Poissaolotapahtumien tuetut kentät
- Yritys-, tiimi- ja toimipistetapahtumat
- Tapahtuman tekijä
- Tietoturva ja vaatimustenmukaisuus
- Usein kysytyt kysymykset
Roolit ja käyttöoikeudet
| Rooli | Käyttöoikeus |
|---|---|
| Järjestelmärooli, jolla on täydet oikeudet kohtaan Organisaatio | Voi määrittää ja hallita webhook-integraatioita |
💡⛓️💥 Kiinnostaako avoin API? Lue tämä artikkeli.
Useat integraatiot
Jos sinun on määritettävä useita webhook-yhteyksiä, noudata näitä ohjeita.
Tuetut ominaisuudet
Työntekijän profiilitapahtumat
- Oma tapahtuma profiiliin kirjautumiseen käytettävän sähköpostiosoitteen muuttamiselle.
- Automaattiset päivitykset, kun käyttäjiä lisätään tai poistetaan – viesti lähetetään automaattisesti aina, kun käyttäjä luodaan tai poistetaan Humassa.
- Reaaliaikaiset päivitykset, kun profiilia muutetaan – tuettujen profiilikenttien muutokset lähetetään automaattisesti rekisteröityyn URL-osoitteeseen.
- Profiilien nykytilan vienti yrityskohtaiset kentät mukaan lukien – hyödyllinen, kun webhookin kautta yhdistettävän järjestelmän tila alustetaan.
Tehtävätapahtumat
- Automaattiset päivitykset, kun tehtäviä luodaan, päivitetään tai poistetaan
Poissaolotapahtumat
- Automaattiset päivitykset, kun poissaoloja kirjataan tai poistetaan
- Reaaliaikaiset päivitykset, kun poissaolomerkintä käsitellään tai sitä muokataan muuten
Yritys-, tiimi- ja toimipistetapahtumat
- Päivitykset, kun yritys, tiimi tai toimipiste luodaan, päivitetään tai poistetaan
- Jäsenyysmuutokset – tapahtumat lähetetään aina, kun käyttäjiä lisätään yritykseen, tiimiin tai toimipisteeseen tai poistetaan niistä
Voinko käyttää webhookeja palvelulle "X"?
Webhookin ja kolmannen osapuolen järjestelmän välissä käytetään usein "välipalvelua". Välipalvelu vastaanottaa webhookin sisällön ja muotoilee sen uudelleen vastaanottavan järjestelmän vaatimusten mukaiseksi. Jotkut asiakkaat antavat oman IT-osastonsa rakentaa tämän palvelun. Toiset käyttävät ulkoisia middleware-toimittajia.
🔗 Katso käytännön esimerkki tästä artikkelista.
Näin määrität webhookin
- Siirry kohtaan "Integraatiot"
- Etsi Webhooks ja valitse "Uusi yhteys"
- Valitse "Määritä"
- Anna URL-osoite, johon webhook-pyynnöt lähetetään, ja noudata ohjeita
Lisäasetukset:
- Client secret (valinnainen) – jos asetettu, jokainen pyyntö sisältää
huma-hmac-sha256-otsakkeen, jossa on JSON-rungon tiiviste allekirjoitettuna salaisuudella. Tämän avulla voit varmistaa, että pyynnöt tulevat Humasta. - Access token (valinnainen) – jos asetettu, se lisätään jokaiseen pyyntöön tavallisena bearer-tokenina.
- Lähetettävät tapahtumat – valitse yksi tai useampi:
- Työntekijän profiilitapahtumat
- Tehtävätapahtumat
- Poissaolotapahtumat
- Yritys-, tiimi- ja toimipistetapahtumat
- HTTP-menetelmä – valitse, lähetetäänkö aina
POSTvai käytetäänkö tapahtumatyyppiä vastaavia HTTP-menetelmiä:DELETEpoistoille,PUTluonneille,PATCHpäivityksille ja niin edelleen.
💡 Kaikki pyynnöt sisältävät huma-topic-otsakkeen ja JSON-rungossa topic-ominaisuuden. Molemmat arvot ovat aina samat.
💡 Kaikkien pyyntöjen rungossa on myös actor-ominaisuus, joka kertoo, kuka tapahtuman käynnisti. Katso Tapahtuman tekijä.
⚠️ Jos pyyntöä ei käsitellä 1 sekunnin kuluessa, se aikakatkaistaan. Suosittelemme, että tallennat vastaanotetut tiedot ja vastaat heti, ja käsittelet tiedot sen jälkeen erillisessä vaiheessa.
Profiilin sähköpostiosoitteen muutostapahtuma
Koska profiilin sähköpostiosoitetta käytetään Humaan kirjautumiseen, sen muuttaminen noudattaa omaa prosessiaan ja se lähetetään omana tapahtumanaan aiheella user-email-update.
💡 Huom: profiililla voi olla myös yksityinen sähköpostiosoite. Yksityisen sähköpostiosoitteen muutokset käsitellään tavallisena profiilikentän päivityksenä ja lähetetään users-update-tapahtumana. Katso Profiilitapahtumat ja Tuetut kentät alla.
Pyynnön runko sisältää yhden user-objektin, jossa on seuraavat kentät:
| Kenttä | JSON-avain | Huomautukset |
|---|---|---|
| Käyttäjätunnus (ID) | id |
Aina mukana. Yksilöllinen, pysyvä UUID (RFC 4122). Ei muutu käyttäjän elinkaaren aikana. |
| Aiempi sähköpostiosoite | oldEmail |
Aina mukana. |
| Uusi sähköpostiosoite | newEmail |
Aina mukana. |
| Työntekijätunnus | employmentId |
Mukana, jos asetettu. Yksilöllinen pyynnön hetkellä, mutta sitä voidaan myöhemmin muuttaa tai se voidaan poistaa. |
Esimerkki:
{ "topic": "user-email-update", "user": { "id": "d96434d7-9506-4d5f-a969-7d1eea8bc3d6", "oldEmail": "jesper@godmat.no", "newEmail": "jesper.blom@godmat.no", "employmentId": "1" } }
💡 Huomaa – työntekijätunnusten yksilöllisyys:
- Huma voi taata yksilöllisyyden, jos asetus "Edellyttää yksilöllistä työntekijätunnistetta" on aina ollut käytössä.
- Huma ei voi taata yksilöllisyyttä, jos vaatimus on jossain vaiheessa poistettu käytöstä. Kaksoiskappaleita voi olla, vaikka vaatimus olisi myöhemmin otettu uudelleen käyttöön, ellei niitä ole korjattu käsin.
Profiilitapahtumat
Profiilitietoja koskeva aihe on jokin seuraavista:
users-createusers-updateusers-deleteusers-export
Kaikkien profiilitapahtumien pyyntörungot sisältävät users-taulukon. Jokainen taulukon objekti sisältää aina kentät id, email, employmentId (jos asetettu) ja status.
Luonti
Lähetetään POST-pyyntönä. Sisältää kaikkien luotujen käyttäjien täydet profiiliobjektit.
Esimerkki:
{ "topic": "users-create", "users": [ { "id": "09d41e51-0963-4763-933b-8c9df093d653", "status": "ACTIVE", "givenName": "Ida", "preferredName": null, "familyName": "Fossdal", "email": "ida.fossdal@godmat.no", "privateEmail": null, "phone": "+47 955 55 167", "address": { "line1": "Fossvegen 82", "line2": null, "postalCode": "1823", "city": "Bergen", "country": "NO" }, "birthDate": "1993-07-29", "nationality": null, "dietaryRequirements": null, "funfacts": null, "interests": null, "bankAccount": { "type": "national", "number": "12345678903", "country": "NO" }, "gender": "Female", "civilStatus": null, "employmentId": "1", "firstDayOfWork": "2001-09-14", "employmentStartDate": "2001-09-14", "lastDayOfWork": null, "employmentEndDate": null, "terminationNoticeDate": null, "terminationDate": null, "employmentType": "Permanent", "employmentPercentage": 100, "jobTitle": "CEO", "jobDescription": "Make the decisions", "identifications": null, "salary": { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "periodUnit": "yearly", "amount": 950000, "currency": "NOK", "fromDate": "2020-01-01", "toDate": null, "current": true, "note": null }, "supervisor": null } ], "actor": { "type": "user", "id": "09d41e51-0963-4763-933b-8c9df093d653", "email": "ida.fossdal@godmat.no", "name": "Ida Fossdal" } }
Poisto
Lähetetään DELETE-pyyntönä. Objektit users sisältävät vain tunnisteet.
Esimerkki:
{ "topic": "users-delete", "users": [ { "id": "d96434d7-9506-4d5f-a969-7d1eea8bc3d6", "email": "jesper.blom@godmat.no", "employmentId": "31", "status": "INACTIVE" } ], "actor": { "type": "user", "id": "09d41e51-0963-4763-933b-8c9df093d653", "email": "ida.fossdal@godmat.no", "name": "Ida Fossdal" } }
Päivitys
Lähetetään PATCH-pyyntönä. Objektit users sisältävät tunnisteet ja vain muuttuneet kentät.
Esimerkki – työntekijä päivittää tilinumeronsa IBAN-muotoon:
{ "topic": "users-update", "users": [ { "id": "d96434d7-9506-4d5f-a969-7d1eea8bc3d6", "email": "jesper.blom@godmat.no", "employmentId": "31", "status": "ACTIVE", "bankAccount": { "type": "international", "iban": "FR7630006000011234567890189", "bic": "AGRIFRPP" } } ], "actor": { "type": "user", "id": "d96434d7-9506-4d5f-a969-7d1eea8bc3d6", "email": "jesper.blom@godmat.no", "name": "Jesper Blom" } }
Vienti
Lähetetään yhtenä tai useampana POST-pyyntönä. Jokainen pyyntö sisältää kaikkien tuettujen kenttien nykytilan enintään 50 käyttäjälle. Jos organisaatiossasi on yli 50 käyttäjää, vienti jaetaan useaan pyyntöön. Esimerkiksi 132 käyttäjän organisaation vienti tuottaa kolme pyyntöä: kaksi, joissa on 50 käyttäjää, ja yhden, jossa on 32.
⚠️ Kenttä "Lapset" ei ole tuettu kenttä, eikä sitä sisällytetä.
Tuetut kentät
| Kenttä | JSON-avain |
|---|---|
| Sähköpostiosoite | email – huom: pääsähköpostiosoitteen muutokset lähetetään erillisenä user-email-update-tapahtumana |
| Tila | status |
| Etunimi | givenName |
| Sukunimi | familyName |
| Kutsumanimi | preferredName |
| Puhelinnumero | phone |
| Yksityinen sähköposti | privateEmail |
| Osoite | address |
| Syntymäaika | birthDate |
| Kansallisuus | nationality |
| Erityisruokavalio | dietaryRequirements |
| Tietoa minusta | funfacts |
| Kiinnostuksenkohteet | interests – joko null tai merkkijonotaulukko |
| Tilinumero | bankAccount – joko null tai objekti, joka sisältää kentän type sekä kaksi lisäkenttää kentän type arvon mukaan. Jos type on national, muut kentät ovat number ja country. Jos type on international, muut kentät ovat iban ja bic. |
| Sukupuoli | gender |
| Siviilisääty | civilStatus |
| Henkilöllisyys | identifications – joko null tai objektitaulukko. Jokainen objekti sisältää kentät id (Human sisäinen tunnus), type (joko national tai passport), value (tunnistenumero) ja country (ISO 3166-1 alpha-2 -maakoodi). |
| Esihenkilö | supervisor – joko null tai objekti, joka sisältää kentän id ja email |
| Työntekijätunnus | employmentId |
Tehtäväkentät
| Kenttä | JSON-avain |
|---|---|
| Työsuhteen aloituspäivä | employmentStartDate |
| Koeajan päättymispäivä | probationEndDate |
| Ensimmäinen työpäivä | firstDayOfWork |
| Irtisanomisilmoituksen päivämäärä | terminationNoticeDate |
| Viimeinen työpäivä | lastDayOfWork |
| Työsuhteen viimeinen päivä | employmentEndDate |
| Työsuhteen tyyppi | employmentType – joko null tai jokin seuraavista: Permanent, Temporary, Seasonal, Casual, Trainee, Job training program, Consultant, Freelance, Third party, Other |
| Työaika prosentteina | employmentPercentage |
| Tehtävänimike | jobTitle |
| Tehtävänkuvaus | jobDescription |
⚠️ Palkka (tulee erillisinä tapahtumina vuonna 2026)
| Kenttä | JSON-avain | Huomautukset |
|---|---|---|
| Palkka | salary |
Objekti, joka sisältää palkkatiedot. Vain nykyinen palkka lähetetään. |
salary.id |
Tämän palkkamerkinnän yksilöllinen tunniste (UUID) | |
salary.periodUnit |
Jokin seuraavista: hourly, weekly, monthly tai yearly |
|
salary.amount |
Desimaaliluku | |
salary.currency |
ISO 4217 -valuuttakoodi | |
salary.fromDate |
Aina mukana | |
salary.toDate |
Valinnainen | |
salary.current |
Totuusarvo, joka kertoo, onko kyseessä työntekijän nykyinen palkka | |
salary.note |
Valinnainen vapaa teksti |
💡 Palkkakenttä lähetetään toistaiseksi profiilitapahtuman kautta.
Yrityskohtaiset kentät
Kaikki organisaatiosi määrittämät yrityskohtaiset kentät sisällytetään päivitystapahtumiin, kun päivitettävä kenttä on yrityskohtainen kenttä, sekä kaikkiin vientitapahtumiin.
Jos tapahtuma sisältää yrityskohtaisia kenttiä, käyttäjäobjekti sisältää custom-ominaisuuden – objektin, jonka avaimina ovat yrityskohtaisten kenttien nimet ja arvoina niiden arvot. Jos yrityskohtaisella kentällä ei ole arvoa, se sisällytetään arvona null.
Esimerkki organisaatiosta, jolla on kaksi yrityskohtaista kenttää, "Paidan koko" ja "Rekisterinumero":
"custom": { "shirtSize": "XL", "licensePlate": null }
Tehtävätapahtumat
Tehtävätietojen osalta aihe on yksi seuraavista:
positions-createpositions-updatepositions-deletepositions-export
Kaikkien tehtävätapahtumien pyyntörungot sisältävät positions-taulukon, jossa on objekti jokaisesta muuttuneesta tehtävästä.
Luonti
Lähetetään POST-pyyntönä. Sisältää koko tehtäväobjektin.
Esimerkki:
{ "topic": "positions-create", "positions": [ { "id": "59307188-bd2d-431a-aa97-97d2b92222dc", "contractStartDate": "2026-02-18", "contractEndDate": null, "firstDayOfWork": "2026-02-18", "lastDayOfWork": null, "contractCountry": "NO", "contractType": "Permanent", "percentage": 100, "probationEndDate": "2026-08-18", "terminationNoticeDate": null, "title": "CMO", "description": "Oversees the company's marketing strategy.", "endNote": null, "endReason": null, "wantedEnd": false, "note": "Team: Development, Company: Tech Inc. Supervisor: Karin Strand!", "user": { "id": "e902714f-a3f9-4cd1-ab04-980a443d77ae", "email": "user-email@company.com" } } ], "actor": { "type": "user", "id": "a558d25a-99d6-45b1-855c-63b052adc5f3", "email": "admin@company.com", "name": "Karina Strand" } }
Päivitys
Lähetetään PATCH-pyyntönä. Sisältää vain muuttuneet kentät.
Esimerkki:
{ "topic": "positions-update", "positions": [ { "id": "5c1de17b-7e47-4827-a1f3-536bb061c2c4", "contractStartDate": "2021-08-18", "firstDayOfWork": "2021-08-18", "contractCountry": "NO", "contractType": "Trainee", "percentage": 75, "probationEndDate": "2022-02-18", "note": "Team: Development, Company: Tech Inc. Supervisor: Karin Strand!", "user": { "id": "e902714f-a3f9-4cd1-ab04-980a443d77ae", "email": "user-email@company.com" } } ], "actor": { "type": "user", "id": "a558d25a-99d6-45b1-855c-63b052adc5f3", "email": "admin@company.com", "name": "Karina Strand" } }
Poisto
Lähetetään DELETE-pyyntönä. Objektit positions sisältävät vain tunnisteet.
Esimerkki:
{ "topic": "positions-delete", "positions": [ { "id": "5c1de17b-7e47-4827-a1f3-536bb061c2c4", "user": { "id": "e902714f-a3f9-4cd1-ab04-980a443d77ae", "email": "user-email@company.com" } } ], "actor": { "type": "user", "id": "a558d25a-99d6-45b1-855c-63b052adc5f3", "email": "admin@company.com", "name": "Karina Strand" } }
Vienti
Kun aktivoit viennin webhook-integraation sivulta, valitset ajanjakson ja sen, minkä käyttäjien tehtävät sisällytetään. Tulos lähetetään yhtenä tai useampana POST-pyyntönä, joista jokainen sisältää enintään 50 tehtävämerkintää.
Esimerkki:
{ "topic": "positions-export", "positions": [ { "id": "12425fdc-e743-4e82-84ca-3036d5cbbb0d", "contractStartDate": "2026-01-20", "contractEndDate": "2026-07-20", "firstDayOfWork": "2026-01-20", "lastDayOfWork": "2026-07-20", "contractCountry": "NO", "contractType": "Permanent", "percentage": 100, "probationEndDate": "2026-04-20", "terminationNoticeDate": "2026-06-20", "title": "Software Engineer", "description": "This is a description of the position.", "endNote": "This is an end note.", "endReason": "employee_terminated", "wantedEnd": false, "note": "Team: Development, Company: Tech Inc.", "user": { "id": "73ced5dd-8bfb-43e0-982b-4b8bb1382c91", "email": "ida.fossdal@godmat.no" } } ], "actor": { "type": "user", "id": "a558d25a-99d6-45b1-855c-63b052adc5f3", "email": "admin@company.com", "name": "Karina Strand" } }
Tuetut kentät
| Kenttä | JSON-avain |
|---|---|
| Tehtävän tunnus (ID) | id |
| Tehtävänimike | title |
| Tehtävänkuvaus | description – joko oma kuvaus tai tehtävänimikkeelle määritetty kuvaus |
| Sopimustyyppi | contractType – joko null tai jokin seuraavista: Permanent, Temporary, Seasonal, Casual, Trainee, Job training program, Consultant, Freelance, Third party, Other |
| Prosenttiosuus | percentage |
| Sopimuksen maa | contractCountry |
| Kommentti | note |
| Sopimuksen alkamispäivä | contractStartDate |
| Ensimmäinen työpäivä | firstDayOfWork |
| Koeajan päättymispäivä | probationEndDate |
| Irtisanomisilmoituksen päivämäärä | terminationNoticeDate |
| Viimeinen työpäivä | lastDayOfWork |
| Sopimuksen päättymispäivä | contractEndDate |
| Päättymisen syy | endReason – joko null tai jokin seuraavista: The employer has terminated the employee, The employee has resigned, The contract, engagement, or temporary position has expired, Changed payroll system or accountant, Other |
| Toivottu päättyminen | wantedEnd — true tai false |
| Perustelut ja huomiot | endNote |
Poissaolotapahtumat
Poissaolotietoja koskeva aihe on jokin seuraavista:
absence-createabsence-updateabsence-deleteabsence-export
Kaikkien poissaolotapahtumien pyyntörungot sisältävät absence-taulukon. Jokainen objekti sisältää merkinnän kaikki tuetut kentät.
Luonti
Lähetetään POST-pyyntönä.
Esimerkki:
{ "topic": "absence-create", "absence": [ { "id": "45be6bce-88f5-4f67-a6de-cbd84df21e1e", "status": "pending", "type": { "name": "vacation" }, "user": { "id": "c2c8d497-352a-4c21-bf7c-aefbaec37717", "email": "patrick.remen@godmat.no" }, "startDate": "2022-10-24", "endDate": "2022-10-28", "grade": 1, "workRelated": false, "note": null, "comment": null, "reviewedAt": null, "reviewedBy": null, "registeredAt": "2022-10-04T11:57:13.819Z", "registeredBy": { "id": "c2c8d497-352a-4c21-bf7c-aefbaec37717", "email": "patrick.remen@godmat.no" } } ], "actor": { "type": "user", "id": "c2c8d497-352a-4c21-bf7c-aefbaec37717", "email": "patrick.remen@godmat.no", "name": "Patrick Remen" } }
Päivitys
Lähetetään PATCH-pyyntönä. Lähetetään, kun käsittelijä muuttaa tilaa, työntekijä muokkaa pyyntöään tai esihenkilö tekee muutoksia työntekijän puolesta.
Esimerkki:
{ "topic": "absence-update", "absence": [ { "id": "e9b5a57f-2f36-462e-aed2-19c6aa990fce", "status": "approved", "type": { "name": "vacation" }, "user": { "id": "c2c8d497-352a-4c21-bf7c-aefbaec37717", "email": "patrick.remen@godmat.no" }, "startDate": "2022-10-10", "endDate": "2022-10-14", "grade": 1, "workRelated": false, "note": null, "comment": null, "reviewedAt": "2022-10-05T11:57:13.819Z", "reviewedBy": { "id": "d96434d7-9506-4d5f-a969-7d1eea8bc3d6", "email": "jesper.blom@godmat.no" }, "registeredAt": "2022-10-04T11:51:08.962Z", "registeredBy": { "id": "c2c8d497-352a-4c21-bf7c-aefbaec37717", "email": "patrick.remen@godmat.no" } } ], "actor": { "type": "user", "id": "d96434d7-9506-4d5f-a969-7d1eea8bc3d6", "email": "jesper.blom@godmat.no", "name": "Jesper Blom" } }
Poisto
Lähetetään DELETE-pyyntönä. Objektit absence sisältävät vain tunnuksen.
Esimerkki:
{ "topic": "absence-delete", "absence": [ { "id": "e9b5a57f-2f36-462e-aed2-19c6aa990fce" } ], "actor": { "type": "user", "id": "d96434d7-9506-4d5f-a969-7d1eea8bc3d6", "email": "jesper.blom@godmat.no", "name": "Jesper Blom" } }
Vienti
Kun aktivoit viennin webhook-integraation sivulta, valitset ajanjakson, sisällytettävät käyttäjät ja sisällytettävät poissaolotyypit. Tulos lähetetään yhtenä tai useampana POST-pyyntönä, joista jokainen sisältää enintään 50 merkintää.
Esimerkki:
{ "topic": "absence-export", "exportFrom": "2022-10-01", "exportTo": "2022-12-31", "absence": [ { "id": "e9b5a57f-2f36-462e-aed2-19c6aa990fce", "status": "approved", "type": { "name": "vacation" }, "user": { "id": "c2c8d497-352a-4c21-bf7c-aefbaec37717", "email": "patrick.remen@godmat.no" }, "startDate": "2022-10-10", "endDate": "2022-10-14", "grade": 1, "workRelated": false, "note": null, "comment": null, "reviewedAt": "2022-10-05T11:57:13.819Z", "reviewedBy": { "id": "d96434d7-9506-4d5f-a969-7d1eea8bc3d6", "email": "jesper.blom@godmat.no" }, "registeredAt": "2022-10-04T11:51:08.962Z", "registeredBy": { "id": "c2c8d497-352a-4c21-bf7c-aefbaec37717", "email": "patrick.remen@godmat.no" } } ], "actor": { "type": "user", "id": "d96434d7-9506-4d5f-a969-7d1eea8bc3d6", "email": "jesper.blom@godmat.no", "name": "Jesper Blom" } }
Tuetut kentät
| Kenttä | JSON-avain |
|---|---|
| Merkinnän tunnus (ID) | id |
| Tila | status – jokin seuraavista: pending, approved tai rejected |
| Tyyppi | type – objekti, joka sisältää kentän name, joka on jokin seuraavista: vacation, selfCertifiedSick, sick, paidTimeOff, unpaidTimeOff, sickChild, parentalLeave |
| Käyttäjä | user – objekti, joka sisältää kentän id ja email |
| Alkamispäivä | startDate |
| Päättymispäivä | endDate |
| Aste | grade – desimaaliluku, jossa 1.0 tarkoittaa 100 % poissaoloa, 0.5 tarkoittaa 50 % jne. |
| Työhön liittyvä | workRelated |
| Kommentti | note – lisätty, kun merkintä kirjattiin |
| Kommentti | comment – lisätty, kun merkintä käsiteltiin |
| Käsitelty | reviewedAt |
| Käsittelijä | reviewedBy – objekti, joka sisältää kentän id ja email |
| Kirjattu | registeredAt |
| Kirjaaja | registeredBy – objekti, joka sisältää kentän id ja email |
Yritys-, tiimi- ja toimipistetapahtumat
Yritys-, tiimi- ja toimipistetietojen osalta aihe on jokin seuraavista:
groups-creategroups-updategroups-deletegroups-exportgroups-add-membersgroups-remove-members
Kaikki tapahtumarungot sisältävät groups-taulukon. Jokainen ryhmäobjekti sisältää aina kentät id, name ja type. Kentän type arvo on COMPANY, TEAM tai LOCATION. Yritysryhmät voivat sisältää myös kentän organizationNumber.
Luonti
Lähetetään POST-pyyntönä.
Esimerkki:
{ "topic": "groups-create", "groups": [ { "id": "<group ID>", "name": "<group name>", "type": "<COMPANY/TEAM/LOCATION>", "description": "<optional group description>", "organizationNumber": "<organization number, Company only>", "links": [ "<link name>\n<link url>" ], "address": { "line1": "Example street 57", "line2": "<optional second line>", "postalCode": "9999", "city": "Demo city", "country": "Theoretia" }, "members": [ { "id": "<user ID>", "email": "<user email>" } ] } ], "actor": { "type": "user", "id": "<user ID>", "email": "<user email>", "name": "<user name>" } }
Päivitys
Lähetetään PUT-pyyntönä.
Esimerkki:
{ "topic": "groups-update", "groups": [ { "id": "<group ID>", "name": "<group name>", "type": "<COMPANY/TEAM/LOCATION>", "description": "<optional group description>", "organizationNumber": "<organization number, Company only>", "links": [ "<link name>\n<link url>" ], "address": { "line1": "Example street 57", "line2": "<optional second line>", "postalCode": "9999", "city": "Demo city", "country": "Theoretia" } } ], "actor": { "type": "user", "id": "<user ID>", "email": "<user email>", "name": "<user name>" } }
Poisto
Lähetetään DELETE-pyyntönä. Ryhmäobjektit sisältävät vain kentät id, name ja type.
Esimerkki:
{ "topic": "groups-delete", "groups": [ { "id": "<group ID>", "name": "<group name>", "type": "<COMPANY/TEAM/LOCATION>" } ], "actor": { "type": "user", "id": "<user ID>", "email": "<user email>", "name": "<user name>" } }
Vienti
Kun aktivoit viennin webhook-integraation sivulta, valitset sisällytettävät ryhmätyypit. Tulos lähetetään yhtenä tai useampana POST-pyyntönä, joista jokainen sisältää enintään 50 ryhmäobjektia.
Esimerkki:
{ "topic": "groups-export", "groups": [ { "id": "<group ID>", "name": "<group name>", "type": "<COMPANY/TEAM/LOCATION>", "description": "<optional group description>", "organizationNumber": "<organization number, Company only>", "links": [ "<link name>\n<link url>" ], "address": { "line1": "Example street 57", "line2": "<optional second line>", "postalCode": "9999", "city": "Demo city", "country": "Theoretia" }, "members": [ { "id": "<user ID>", "email": "<user email>" } ] } ], "actor": { "type": "user", "id": "<user ID>", "email": "<user email>", "name": "<user name>" } }
Jäsenten lisääminen
Lähetetään PUT-pyyntönä.
Esimerkki:
{ "topic": "groups-add-members", "groups": [ { "id": "<group ID>", "name": "<group name>", "type": "<COMPANY/TEAM/LOCATION>", "members-added": [ { "id": "<user ID>", "email": "<user email>" } ] } ], "actor": { "type": "user", "id": "<user ID>", "email": "<user email>", "name": "<user name>" } }
Jäsenten poistaminen
Lähetetään PUT-pyyntönä.
Esimerkki:
{ "topic": "groups-remove-members", "groups": [ { "id": "<group ID>", "name": "<group name>", "type": "<COMPANY/TEAM/LOCATION>", "members-removed": [ { "id": "<user ID>", "email": "<user email>" } ] } ], "actor": { "type": "user", "id": "<user ID>", "email": "<user email>", "name": "<user name>" } }
Tapahtuman tekijä
Jokainen tapahtumarunko sisältää actor-objektin, joka kertoo, kuka tapahtuman käynnisti. Luonti-, päivitys- ja poistotapahtumissa se on käyttäjä, joka teki muutoksen. Vientitapahtumissa se on käyttäjä, joka käynnisti viennin.
💡 Osa toiminnoista käynnistyy integraatioiden eikä käyttäjien toimesta. Silloin actor-objektin kentän type arvo on integration.
| Kenttä | JSON-avain | Huomautukset |
|---|---|---|
| Tekijän tunnus (ID) | id |
Aina mukana. Pysyvä UUID. Integraatiotekijöillä tunnus säilyy samana, kun yhteys katkaistaan ja muodostetaan uudelleen, mutta muuttuu, jos yhteys poistetaan ja luodaan uudelleen. |
| Tekijän tyyppi | type |
Aina mukana. Joko user tai integration. |
| Sähköposti | email |
Mukana, kun type on user. Yksilöllinen pyynnön hetkellä, mutta voi muuttua, jos käyttäjän sähköpostiosoite päivitetään. |
| Nimi | name |
Tekijän nimi. |
Tietoturva ja vaatimustenmukaisuus
Kun luot yhteyden webhookien kautta, valtuutat Human käyttämään webhook-päätepistettäsi käyttöehtojemme kohdan Third-Party Platforms mukaisesti.
Usein kysytyt kysymykset
Mitä tapahtuu, jos päätepisteeni ei vastaa ajoissa?
Huma odottaa vastausta 1 sekunnin kuluessa. Jos päätepisteesi ei vastaa ajoissa, pyyntö aikakatkaistaan. Suosittelemme, että kuittaat pyynnön heti ja käsittelet tiedot asynkronisesti.
Miksi saan users-update-tapahtuman, kun tehtävä muuttuu?
Kun tehtävän muutos vaikuttaa työntekijän nykyiseen ensisijaiseen tehtävään, Huma lähettää myös users-update-tapahtuman, jotta käyttäjäprofiilin vanhentuneet tehtäväkentät pysyvät synkronoituina. Tämä on odotettua toimintaa.
Voinko käyttää samaa webhook-URL-osoitetta useille tapahtumatyypeille?
Kyllä. Voit määrittää yhden webhook-yhteyden vastaanottamaan mitä tahansa profiili-, tehtävä-, poissaolo- ja ryhmätapahtumien yhdistelmää. Tunnista tapahtumatyyppi kunkin pyynnön topic-kentästä.
Mitä poissaolotapahtumien grade-kenttä tarkoittaa?
grade on desimaaliluku, joka kuvaa poissaolon astetta. Arvo 1.0 tarkoittaa, että työntekijä on kokonaan poissa, 0.5 tarkoittaa 50 % ja niin edelleen.
Miten voin varmistaa, että pyyntö todella tulee Humasta?
Aseta client secret, kun määrität webhookin. Jokainen pyyntö sisältää silloin huma-hmac-sha256-otsakkeen, jossa on pyynnön rungon tiiviste allekirjoitettuna salaisuudellasi. Tarkista tiiviste omalla puolellasi varmistaaksesi, että pyyntö on aito.
Mikä on employmentId ja voiko se muuttua?
employmentId on yksilöllinen tunniste, jonka annat työntekijöille Humassa. Se on yksilöllinen pyynnön lähetyshetkellä, mutta käyttäjä, jolla on tarvittavat oikeudet, voi muuttaa tai poistaa sen. Älä oleta, että se pysyy samana kaikissa tulevissa pyynnöissä.
Sisältyykö poissaolokäytännön vientikoodi webhookin sisältöön?
Ei. Vientikoodi on Humassa poissaolotyypin käytännön asetuskenttä, eikä sitä sisällytetä webhookin sisältöön. Poissaolotapahtumat sisältävät poissaolotyypin nimen (esim. vacation, sick) mutta eivät käytäntötason asetuksia, kuten vientikoodia.