Send data til dine systemer med webhooks

En webhook sender data til en URL, du vælger, i det øjeblik noget sker, fx når nogen deltager i en kampagne eller vinder en præmie. Din udvikler sætter det system op, der modtager dataene.

Webhooks indgår i de abonnementer, der har Webhooks og API (Basic og opefter).

Kampagnewebhooks eller kontowebhooks?

• Kampagnewebhooks sættes op i kampagneeditoren og udløses kun for den kampagne. De har hændelserne "Hver gang et lead deltager i en kampagne" og "Når et lead vinder en præmie" og flest muligheder.
• Kontowebhooks sættes op under Indstillinger > Webhooks. De har hændelsen "Når et nyt lead oprettes": den udløses én gang pr. person, første gang personen bliver tilføjet til dine leads, uanset hvilken kampagne personen kom fra.

Tilføj en webhook til en kampagne

1. Åbn kampagnen i editoren, og gå til Forbind > Webhooks.
2. Klik på Tilføj webhook.
3. Angiv Payload-URL. Den skal starte med https: "Vi understøtter kun webhooks over HTTPS for at sikre, at de sendte data forbliver sikre."
4. Vælg Indholdstype: application/json eller application/x-www-form-urlencoded.
5. Vælg Metode. Formularen starter på GET, som sender dataene i URL'en. Vælg POST for at sende dem i body'en, hvilket de fleste systemer forventer.
6. Under Godkendelse (kun for POST) vælger du Basic Auth, hvis din URL kræver brugernavn og adgangskode, og udfylder Brugernavn og Adgangskode. Ellers beholder du Ingen.
7. Angiv et Secret til at signere forespørgslerne (anbefales). Se "Tjek signaturen" nedenfor.
8. Slå Log svarets indhold til, hvis du vil se, hvad dit system svarer. "Aktivér for at gemme svarets indhold til fejlfinding."
9. Lad Aktiv være slået til. "Vi leverer kun hændelser, hvis webhooken er aktiv."
10. Vælg hændelsen: "Hver gang et lead deltager i en kampagne" eller "Når et lead vinder en præmie".
11. Slå Brugerdefineret payload til, hvis du selv vil bestemme felterne (se nedenfor).
12. Klik på Tilføj webhook. Du ser "Webhook tilføjet".

Panelet Webhooks viser kampagnens webhooks med Aktiv eller Inaktiv og Seneste levering mislykkedes, hvis den seneste forespørgsel mislykkedes. Under Handlinger kan du vælge Redigér, Se leveringer eller Slet for en webhook. Når du redigerer en webhook, lader du Secret stå tomt for at beholde det, du har.

Tilføj en kontowebhook

1. Gå til Indstillinger > Webhooks (under Udviklere). Dine webhooks står under Mine webhooks (eller under hver leadlistes navn, hvis du har flere).
2. Klik på kortet med plusset for at tilføje en webhook. Dialogen Tilføj webhook siger "Send en anmodning til en ekstern URL, når valgte hændelser sker."
3. Udfyld Payload-URL, Indholdstype ("Vælg webhookens indholdstype"), Metode og Secret som ovenfor.
4. Under Hvilke hændelser skal udløse webhooken? vælger du "Når et nyt lead oprettes".
5. Sæt flueben i "Ja, lad mig angive en brugerdefineret payload (kun for avancerede brugere)", hvis du vil have dine egne felter.
6. Sæt flueben i Log svarets indhold ("Denne webhook logger svarets indhold"), hvis du har brug for det, og lad fluebenet i Aktiv blive stående ("Vi leverer hændelsesdetaljer, når denne hook udløses").
7. Klik på Tilføj webhook.

Klik på en webhook for at ændre den (Gem ændringer), angive et Nyt secret, åbne Vis leveringer eller Slet webhook ("Denne handling kan ikke fortrydes!").

Hvad der sendes

Som standard har body'en en event (hændelsens navn: lead_created_on_campaign, new_campaign_winner eller lead_created) og et data-objekt:

• campaign: kampagnens id og name (kampagnewebhooks)
• lead: leadets formularfelter efter deres feltnøgle (fx first_name) plus id, phone_number og created_at
• lead.permissions: for hvert afkrydsningsfelt til samtykke, om det blev accepteret, teksten, datoen og IP-adressen (kampagnewebhooks)
• participant: den channel, personen kom fra, og hvornår personen deltog (kampagnewebhooks)
• quiz: svarene på navngivne quizspørgsmål, også under læsbare navne, der starter med "Simple"
• prize: præmiens id, name, value, coupon_code og hvornår den blev vundet (vinderwebhooks)

Tomme værdier udelades, og det samme gør samtykker, der ikke blev accepteret. Med metoden GET bliver de samme data sendt som query-parametre i URL'en.

Brugerdefineret payload

Med Brugerdefineret payload slået til bliver kun de felter, du vælger, sendt, og der er ingen event-indpakning.

1. Under Datatilknytning klikker du på Tilføj tilknytning.
2. Skriv det Feltnavn, dit system forventer. Brug bogstaver, tal, bindestreger og understregninger.
3. Vælg det Scratcher-felt, der skal sendes ("Gruppe → Felt"), eller Brugerdefineret værdi, og skriv en fast Værdi.
4. Gentag for hvert felt. Fjern et felt med skraldespanden (Fjern eller Fjern datatilknytning).

Tjek signaturen

Har du angivet et secret, har hver forespørgsel en X-Hub-Signature-header: sha1= efterfulgt af en HMAC-SHA1-hash af den JSON-kodede payload (body'en som beskrevet ovenfor) med dit secret som nøgle. Beregn det samme på din side, og sammenlign, så du er sikker på, at forespørgslen kom fra Scratcher.

Leveringer og nye forsøg

• Svarer din URL ikke, eller returnerer den en fejl (status 400 eller højere), prøver Scratcher igen to gange: efter 5 sekunder og efter et minut.
• Omdirigeringer bliver ikke fulgt, så brug den endelige URL.
• Åbn leveringerne (Se leveringer i kampagnen, Vis leveringer for kontowebhooks) for at se hver forespørgsel og hvert svar. Hver levering viser sit ID, Anmodning og Svar med statuskoden (og Svarets indhold, hvis du logger det). Brug kopiér til at kopiere en payload.
• Slå Vis kun mislykkede leveringer til for kun at se problemerne. Øverst står "Mislykkede leveringer de seneste 60 dage".
• Klik på Prøv igen for at sende en levering igen: "Webhooken sendes igen."
• "Logs over webhook-leveringer gemmes i 60 dage."

Fejlfinding

• "Feltet ... skal bruge HTTPS.": Payload-URL starter med http. Brug https.
• Alle leveringer mislykkes uden svar: URL'en kan ikke nås fra internettet, fx en lokal eller intern adresse. Brug en offentlig URL.
• Dit system får ingen data: metoden er GET, så dataene ligger i URL'en. Skift til POST.
• Et felt, dit system forventer, mangler: det var tomt, eller samtykket blev ikke accepteret. Lad dit system behandle manglende felter som tomme.