Gratis setup bij jaarabonnementen

Nu inschrijven!
Plan een demo

Webhooks

Home

> API-referentie >

Eindpunten >

Webhooks

API-referentie: Webhooks-endpoints

Het huidige AnswerPal webhook-aanbod bestaat uit het verwerken van Microsoft Graph e-mailnotificaties. Het valideert Microsoft Graph subscription-handshakes, ontvangt Graph-mailnotificaties en schakelt de Graph-abonnementsstatus om voor een Office365 e-mailkanaal.

Huidige endpoints

Graph callback-routes

Dit is geen generieke outbound webhook-configuratie-API. AnswerPal workflow- en gebeurtenisautomatisering wordt ondersteund door de Hooks API. De onderstaande Webhooks-endpoints bestaan zodat Microsoft Graph kan terugkoppelen naar AnswerPal wanneer er nieuwe berichten binnenkomen in geabonneerde mailmappen.

  • GET /api/GraphWebhook – Public
    Microsoft Graph validatiecallback. Indien de queryparameter validationToken aanwezig is, retourneert AnswerPal deze waarde als text/plain. Zonder token retourneert de route 400 Bad Request.
  • POST /api/GraphWebhook – Public
    Microsoft Graph notificatiecallback. Een query validationToken wordt gespiegeld als text/plain. Anders wordt de JSON-body gelezen en kan elke notificatie automatisch een e-mailimporttaak inplannen wanneer het abonnement, de map en het kanaal overeenkomen met de huidige instellingen voor automatisch ophalen.

Validatiecallback

GET /api/GraphWebhook?validationToken={token}

200 OK
Content-Type: text/plain

{token}

Callbackgedrag

Huidig routeringsgedrag

  • validationToken
    Wordt gebruikt door Microsoft Graph ter validatie van abonnementen. Zowel GET als POST geven de ruwe token terug als text/plain wanneer de queryparameter is opgegeven.
  • Lege POST-body
    Wordt geaccepteerd en geeft 200 OK terug. Niet-lege body’s worden gedeserialiseerd als GraphWebhookPayload.
  • Abonnementslookup
    De callback resolveert eerst subscriptionId via de Graph subscription service. Indien dat mislukt, kan het het Graph resource-pad parsen en het kanaalmappen opzoeken via mailbox en externe map-ID.
  • Importtrigger
    Een notificatie plant enkel een automatische mapimport in wanneer de map bestaat, de map AutoRetrieveEmails actief heeft en het kanaal ook AutoRetrieveEmails actief heeft staan.

Graph-abonnementsservice

  • E-mailprovider
    Abonnementen worden enkel aangemaakt voor e-mailkanalen waarvan de effectieve provider Office365 is. Andere e-mailproviders worden door de Graph-abonnementsservice overgeslagen.
  • Graph resource
    Mapabonnementen gebruiken /users/{mailbox}/mailFolders('{folderId}')/messages en changeType = created.
  • Vervaldatum
    Abonnementen worden aangemaakt of vernieuwd met een vervaldatum ongeveer drie dagen in de toekomst. Vernieuwingen worden geprobeerd wanneer de opgeslagen vervaldatum binnen een uur valt.
  • Notificatie-URL
    De subscribe/unsubscribe-endpoints bouwen de callback op basis van de BackendAPI-configuratiewaarde als {BackendAPI}/api/graphwebhook.

Notificatiepayload

POST /api/GraphWebhook
Content-Type: application/json

{
  "value": [
    {
      "subscriptionId": "00000000-0000-0000-0000-000000000000",
      "resource": "/users/[email protected]/mailFolders('Inbox')/messages",
      "resourceData": {
        "id": "AAMkAG..."
      }
    }
  ]
}

Toegang en responsegedrag

Toegangsmodel

  • GET /api/GraphWebhook en POST /api/GraphWebhook
    Deze callbackroutes zijn gemarkeerd als Public omdat Microsoft Graph moet kunnen valideren en notificaties versturen.
  • subscribe en unsubscribe
    Deze abonnementsroutes zijn operationele beheerendpoints. Gebruik ze alleen vanuit vertrouwde admintooling.
  • De meeste AnswerPal API-endpoints
    Beschermde AnswerPal API-endpoints gebruiken JWT Bearer-authenticatie. De Webhooks-callback is een gedocumenteerde uitzondering omdat deze door Microsoft Graph wordt aangeroepen.

Algemene statuscodes

  • 200 OK
    Wordt geretourneerd bij succesvolle validatie, geaccepteerde notificaties, lege callback-bodies en geslaagde subscribe/unsubscribe-operaties.
  • 400 Bad Request
    Wordt geretourneerd door GET callback-validatie wanneer geen validationToken querywaarde aanwezig is.
  • 404 Not Found
    Wordt uitgeserveerd door subscribe/unsubscribe wanneer het kanaal niet bestaat, verwijderd is of geen e-mailadres heeft.
GET /api/GraphWebhook?validationToken={token}

200 OK
Content-Type: text/plain

{token}
POST /api/GraphWebhook
Content-Type: application/json

{
  "value": [
    {
      "subscriptionId": "00000000-0000-0000-0000-000000000000",
      "resource": "/users/[email protected]/mailFolders('Inbox')/messages",
      "resourceData": {
        "id": "AAMkAG..."
      }
    }
  ]
}
POST /api/GraphWebhook/subscribe/{channelId}

200 OK
POST /api/GraphWebhook/unsubscribe/{channelId}

200 OK

Abonnement-toggles

De subscribe- en unsubscribe-routes zijn operationele hulpmiddelen rond dezelfde Microsoft Graph-abonnementsservice die gebruikt wordt voor automatisch ophalen van e-mails.

  • POST /api/GraphWebhook/subscribe/{channelId} – Operationele route
    Zet AutoRetrieveEmails aan voor het kanaal en de mappen, en roept vervolgens de Graph-abonnementsservice aan. Het kanaal moet bestaan, mag niet verwijderd zijn en moet een e-mailadres hebben.
  • POST /api/GraphWebhook/unsubscribe/{channelId} – Operationele route
    Zet AutoRetrieveEmails uit voor het kanaal en zijn mappen, en roept vervolgens de Graph-abonnementsservice aan zodat actieve mapabonnementen worden verwijderd of gewist.

Subscribe-voorbeeld

POST /api/GraphWebhook/subscribe/{channelId}

200 OK

Unsubscribe-voorbeeld

POST /api/GraphWebhook/unsubscribe/{channelId}

200 OK

Velden en gedrag

Graph webhook-payload

GraphWebhookPayload

  • value
    Array van Microsoft Graph notificatieobjecten. AnswerPal verwerkt elke notificatie afzonderlijk.

GraphNotification

  • subscriptionId
    Graph-abonnementsidentificatie. Wordt gebruikt als primaire sleutel om naar de geabonneerde map te zoeken.
  • resource
    Optioneel Graph resourcepad. De huidige fallback-parsing verwacht /users/{mailbox}/mailFolders('{folderId}')/messages.
  • resourceData.id
    Graph-berichtidentificatie meegegeven in de notificatiepayload. Dit wordt door de DTO geaccepteerd, maar AnswerPal gebruikt de context van abonnement/map om een mapimport in de wachtrij te plaatsen.

Opgeslagen mapabonnementsvelden

  • GraphSubscriptionId
    Opgeslagen bij kanaalmappen nadat Microsoft Graph het abonnement heeft aangemaakt.
  • GraphSubscriptionExpiration
    Opgeslagen vervaltijdstempel dat wordt gebruikt door de achtergrondvernieuwing.
  • AutoRetrieveEmails
    Schakelaar op kanaal- en mapniveau die bepaalt of Graph-notificaties automatische import kunnen activeren.

Toegangsnormen

Toegangsmodel

  • GET /api/GraphWebhook en POST /api/GraphWebhook
    Deze callbackroutes zijn gemarkeerd als Public omdat Microsoft Graph validatie en notificaties moet kunnen bezorgen.
  • subscribe en unsubscribe
    Deze abonnementsroutes zijn operationele beheerendpoints. Gebruik ze alleen vanuit vertrouwde admintooling.
  • De meeste AnswerPal API endpoints
    Beschermde AnswerPal API endpoints gebruiken JWT Bearer-authenticatie. De Webhooks-callback is een gedocumenteerde uitzondering omdat deze wordt opgeroepen door Microsoft Graph.

Gebruikelijke statuscodes

  • 200 OK
    Wordt geretourneerd bij succesvolle validatie, geaccepteerde notificaties, lege callback-bodies en geslaagde subscribe/unsubscribe acties.
  • 400 Bad Request
    Wordt geretourneerd bij GET callback-validatie als er geen validationToken querywaarde is meegegeven.
  • 404 Not Found
    Wordt geretourneerd bij subscribe/unsubscribe wanneer het kanaal niet bestaat, verwijderd is of geen e-mailadres heeft.

Voor klantconfigureerbare workflowacties, hook-acties, hook-documenten en runtime-hooks voor ticketberichten gebruikt u de Hooks API-referentie. Voor e-mailkanaalinstellingen, mapbeheer, verbindingstesten en kanaaltranslatieroutes gebruikt u de Kanalen API-referentie.

Neen. De huidige Webhooks-interface is bedoeld voor Microsoft Graph e-mailnotificatie-callbacks en abonnementschakelaars. AnswerPal-eventautomatisering wordt gedocumenteerd op de Hooks-endpointpagina.

Microsoft Graph moet de validatie- en notificatie-callback kunnen aanroepen zonder een AnswerPal-gebruikerstoken. Daarom zijn de routes gemarkeerd als Public.

De callback moet een kanaalmap oplossen, en zowel de map als het kanaal moeten AutoRetrieveEmails ingeschakeld hebben. Als aan die voorwaarden wordt voldaan, plaatst AnswerPal automatisch een mapimporttaak in de wachtrij.

Inhoudstafel

AnswerPal: AI-gedreven oplossingen voor klantenservice die je ondersteuning en communicatie moeiteloos versterken.

Snelle links

Contact

Voor ondersteunings-, commerciële en partnervragen kunt u mailen naar [email protected]

AnswerPal
Bisschoppenhoflaan 380
2100 Antwerpen
België

+32.36416685

BE 0862.692.858

Sociale media