Ontwikkelaars: API en toegangstokens

Geef je eigen ontwikkelaars toegang tot je werkruimte met een toegangstoken, en krijg een bericht in je eigen systemen als er iets verandert.

NieuwAbonnement Pro en BusinessVoor Eigenaar6 min
Wat je leert
  • Waarvoor je toegangstokens en webhooks gebruikt
  • Een toegangstoken maken, bewaren en intrekken
  • Een webhook instellen, testen en opvolgen
  • Veilig werken met tokens en geheimen

Bij Instellingen › Ontwikkelaars geef je je eigen ontwikkelaars toegang tot je werkruimte. Zo verbinden ze Ringlane met jullie eigen systemen, bijvoorbeeld Zapier, een intern dashboard of een datawarehouse.

  • Toegangstokens: met een toegangstoken leest en schrijft je eigen koppeling in Ringlane, binnen de rechten die je kiest.
  • Webhooks: Ringlane stuurt een bericht naar je eigen systeem zodra er iets wijzigt, bijvoorbeeld een nieuw record of een ingeplande afspraak.

De technische uitleg voor ontwikkelaars staat op ringlane.ai/developers.

Wie en welk abonnement

Eigenaars en beheerders zien Ontwikkelaars bij Instellingen, onder Werkruimte. Alleen de eigenaar maakt en beheert toegangstokens en webhooks: ze geven toegang tot de gegevens van de hele werkruimte. Een beheerder ziet daarom Alleen voor de eigenaar.

Toegangstokens en webhooks zitten in Pro en Business, ook tijdens de proefperiode van Pro. In Free en Plus zie je Dit zit in Pro, met de knop Abonnementen bekijken.

Ontwikkelaars is voor wie zelf software bouwt. Wil je Google, Attio of Aircall koppelen, gebruik dan Apps.

Een toegangstoken maken

  1. Ga naar Instellingen › Ontwikkelaars › Toegangstokens.
  2. Klik op Nieuw toegangstoken.
  3. Geef het token bij Naam een naam die zegt waarvoor het dient, bijvoorbeeld "Zapier" of "Ons datawarehouse".
  4. Kies bij Verloopt na hoe lang het token werkt: 7 dagen, 30 dagen, 90 dagen of 1 jaar. Standaard 90 dagen.
  5. Kies per onderdeel Uit, Lezen of Lezen en schrijven. Alles staat eerst op Uit; geef minstens één onderdeel toegang.
  6. Klik op Token maken.
  7. Klik in het venster Kopieer je toegangstoken op Kopiëren, bewaar het token en klik op Ik heb het bewaard.

Je ziet een toegangstoken maar één keer, bij het aanmaken. Ringlane kan het je later niet meer tonen, ook niet aan jou. Bewaar het in een wachtwoordbeheerder of bij de geheimen van je koppeling, nooit in code, een document of een chat. Ben je het kwijt, trek het dan in en maak een nieuw.

De onderdelen

OnderdeelWat een token kanRechten
RecordsLeads bekijken, en eventueel aanmaken, wijzigen en verwijderenLezen, of lezen en schrijven
CampagnesCampagnes bekijken, en eventueel aanmaken en wijzigenLezen, of lezen en schrijven
Activiteiten en notitiesGesprekken, uitkomsten en notities bij een record bekijken, en eventueel notities toevoegenLezen, of lezen en schrijven
TakenTerugbelmomenten en opvolgtaken bekijken, en eventueel inplannen of wissenLezen, of lezen en schrijven
AfsprakenIngeplande afspraken met leads bekijkenLezen
LedenDe leden van de werkruimte bekijken: naam, e-mailadres en rolLezen
Velden en statussenDe eigen velden, de statussen en de soorten taken bekijkenLezen

Geef alleen wat de koppeling nodig heeft. Een token geeft toegang tot de gegevens van de hele werkruimte, binnen deze rechten. Een werkruimte heeft hoogstens 25 geldige toegangstokens.

Tokens beheren en intrekken

Bij Toegangstokens staat elk token met zijn naam en zijn rechten, zoals Records: lezen en schrijven. Je ziet wanneer en door wie het gemaakt is, wanneer het laatst gebruikt werd (of Nog niet gebruikt) en tot wanneer het werkt. Van het token zelf zie je alleen een stukje, zodat je het herkent.

Trek een token in als je het niet meer nodig hebt, als een ontwikkelaar vertrekt of als je denkt dat iemand anders het kent: klik op de drie puntjes en kies Intrekken. Het token werkt meteen niet meer en de koppeling die het gebruikt, krijgt geen toegang meer. Dat kan niet ongedaan gemaakt worden.

Een token stopt ook vanzelf. Dan staat er een label bij:

  • Verlopen: de geldigheid is voorbij.
  • Werkt niet meer: wie het token maakte, is geen eigenaar meer van deze werkruimte. Maak een nieuw token.

Onderaan staat het Logboek: de laatste 50 acties met tokens, webhooks en de API in deze werkruimte, zoals een token dat gemaakt of ingetrokken werd, met wie het deed en wanneer.

Webhooks: berichten naar je eigen systemen

Met een webhook stuurt Ringlane een ondertekend bericht naar je eigen systeem zodra er iets wijzigt. Je systeem hoeft dan niet steeds zelf te kijken of er iets nieuw is. Een bericht bevat alleen kenmerken, nooit namen of nummers.

  1. Ga naar Instellingen › Ontwikkelaars › Webhooks en klik op Webhook maken.
  2. Vul bij Doel-URL het adres in waar je systeem de berichten ontvangt: een openbaar adres dat begint met https.
  3. Vink bij Gebeurtenissen aan waarover je een bericht wilt. Met Zoek gebeurtenissen vind je er snel een.
  4. Klik op Webhook maken.
  5. Kopieer in het venster Kopieer het geheim van je webhook het geheim, geef het aan je ontwikkelaar en klik op Ik heb het bewaard. Je systeem controleert er elk bericht mee, zodat het weet dat het echt van Ringlane komt. Ringlane toont het geheim niet opnieuw.
  6. Kies met de drie puntjes bij de webhook Testbericht sturen om te zien of je systeem het ontvangt.
GebeurtenisWanneer
Record aangemaakt, Record gewijzigd, Record verwijderdEen lead kwam erbij, veranderde of werd verwijderd
Activiteit toegevoegdEr kwam een gesprek, uitkomst of notitie bij een record
Afspraak ingeplandEr werd een afspraak met een lead ingepland
Campagne aangemaakt, Campagne gewijzigd, Campagne verwijderdEen campagne kwam erbij, veranderde of werd verwijderd

Een werkruimte heeft hoogstens 10 webhooks. Zie je bij Webhooks Webhooks komen binnenkort, dan werken toegangstokens al en volgen webhooks later.

Een webhook opvolgen

Bij elke webhook zie je zijn adres, zijn gebeurtenissen en zijn status: Actief, Uit of Uitgezet na fouten. Je ziet ook wanneer er laatst iets afgeleverd werd, hoeveel berichten er nog wachten en hoeveel er in de laatste 7 dagen mislukten. Met de drie puntjes kies je:

  • Testbericht sturen: Ringlane zegt meteen of het testbericht afgeleverd is.
  • Afleveringen bekijken: de laatste berichten, elk met Wacht, Bezig, Afgeleverd, Mislukt of Geannuleerd, het aantal pogingen en wanneer Ringlane het opnieuw probeert. Een mislukt bericht stuur je opnieuw met Opnieuw.
  • Bewerken: het adres of de gebeurtenissen wijzigen.
  • Nieuw geheim: het huidige geheim werkt meteen niet meer. Geef het nieuwe geheim meteen aan je ontwikkelaar.
  • Uitzetten of Aanzetten. Wat nog wachtte toen je hem uitzette, wordt niet meer verstuurd.
  • Verwijderen: Ringlane stuurt niets meer naar dit adres en de lijst met afleveringen verdwijnt.

Mislukt drie dagen lang elke aflevering, dan zet Ringlane de webhook uit: Uitgezet na fouten. Kijk de afleveringen na, los het probleem op en zet de webhook weer aan.

Veilig werken

  • Behandel een token en het geheim van een webhook als een wachtwoord. Bewaar ze in een wachtwoordbeheerder of bij de geheimen van je koppeling, nooit in code, een document of een chat.
  • Maak één token per koppeling, met een naam die zegt waarvoor het dient. Zo trek je er één in zonder de rest te storen.
  • Geef alleen de rechten die nodig zijn. Moet een koppeling alleen lezen, kies dan Lezen.
  • Kies de kortste geldigheid die werkt, en maak op tijd een nieuw token.
  • Kijk geregeld wanneer elk token laatst gebruikt werd, en trek tokens in die niemand meer gebruikt.
  • Denk je dat iemand anders het geheim van een webhook kent, kies dan Nieuw geheim.

Als het niet lukt

  • Je ziet Ontwikkelaars niet: alleen eigenaars en beheerders zien deze pagina.
  • Je ziet Alleen voor de eigenaar: alleen de eigenaar maakt en beheert tokens en webhooks.
  • Je ziet Dit zit in Pro: toegangstokens en webhooks zitten in Pro en Business.
  • Een token werkt niet meer: kijk of het Verlopen is, ingetrokken werd of Werkt niet meer toont. Maak zo nodig een nieuw.
  • Je kunt geen nieuw token maken: je hebt er al 25 die nog werken. Trek er een in die je niet meer gebruikt.
  • Het adres van een webhook wordt geweigerd: gebruik een openbaar adres dat begint met https. Een intern adres van je bedrijf kan niet.
  • Een webhook staat op Uitgezet na fouten: kijk de afleveringen na, los het op en zet hem weer aan.
  • Je abonnement gaat naar Free of Plus: Ringlane toont vooraf wat er verandert. Toegangstokens en webhooks stoppen dan.