Free setup on annual plans

Sign up today!
Book a Demo

Webhooks

Home

> API Reference >

Endpoints >

Webhooks

API Reference: Webhooks endpoints

The current AnswerPal webhook surface is Microsoft Graph email notification handling. It validates Microsoft Graph subscription handshakes, receives Graph mail notifications and toggles Graph subscription state for an Office365 email channel.

Current endpoints

Graph callback routes

This is not a generic outbound webhook configuration API. AnswerPal workflow and event automation is covered by the Hooks API. The Webhooks endpoints below exist so Microsoft Graph can call back into AnswerPal when new messages arrive in subscribed mail folders.

  • GET /api/GraphWebhook – Public
    Microsoft Graph validation callback. If query parameter validationToken is present, AnswerPal returns that value as text/plain. Without a token the route returns 400 Bad Request.
  • POST /api/GraphWebhook – Public
    Microsoft Graph notification callback. A query validationToken is echoed as text/plain. Otherwise the JSON body is read and each notification can enqueue an automatic email import job when the subscription, folder and channel match current auto-retrieve settings.

Validation callback

GET /api/GraphWebhook?validationToken={token}

200 OK
Content-Type: text/plain

{token}

Callback behavior

Current routing behavior

  • validationToken
    Used by Microsoft Graph subscription validation. Both GET and POST return the raw token as text/plain when the query parameter is present.
  • Empty POST body
    Accepted and returns 200 OK. Non-empty bodies are deserialized as GraphWebhookPayload.
  • Subscription lookup
    The callback first resolves subscriptionId through the Graph subscription service. If that fails, it can parse the Graph resource path and look up the channel folder by mailbox and external folder ID.
  • Import trigger
    A notification enqueues an auto-folder import only when the folder exists, the folder has AutoRetrieveEmails enabled and the channel also has AutoRetrieveEmails enabled.

Graph subscription service

  • Email provider
    Subscriptions are created only for email channels whose effective provider is Office365. Other email providers are skipped by the Graph subscription service.
  • Graph resource
    Folder subscriptions use /users/{mailbox}/mailFolders('{folderId}')/messages and changeType = created.
  • Expiration
    Subscriptions are created or renewed with an expiration approximately three days in the future. Renewals are attempted when the stored expiration is within one hour.
  • Notification URL
    The subscribe/unsubscribe endpoints build the callback from the BackendAPI configuration value as {BackendAPI}/api/graphwebhook.

Notification payload

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

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

Access and responses

Access model

  • GET /api/GraphWebhook and POST /api/GraphWebhook
    These callback routes are marked Public because Microsoft Graph must be able to validate and deliver notifications.
  • subscribe and unsubscribe
    These subscription-management routes are operational routes. Use them only from trusted admin tooling.
  • Most AnswerPal API endpoints
    Protected AnswerPal API endpoints use JWT Bearer authentication. The Webhooks callback is a documented exception because it is called by Microsoft Graph.

Common status codes

  • 200 OK
    Returned for successful validation, accepted notifications, empty callback bodies and successful subscribe/unsubscribe operations.
  • 400 Bad Request
    Returned by GET callback validation when no validationToken query value is provided.
  • 404 Not Found
    Returned by subscribe/unsubscribe when the channel does not exist, is deleted or has no email address.
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/support@example.com/mailFolders('Inbox')/messages",
      "resourceData": {
        "id": "AAMkAG..."
      }
    }
  ]
}
POST /api/GraphWebhook/subscribe/{channelId}

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

200 OK

Subscription toggles

The subscribe and unsubscribe routes are operational helpers around the same Microsoft Graph subscription service used by automatic email retrieval.

  • POST /api/GraphWebhook/subscribe/{channelId} – Operational route
    Turns AutoRetrieveEmails on for the channel and its folders, then calls the Graph subscription service. The channel must exist, must not be deleted and must have an email address.
  • POST /api/GraphWebhook/unsubscribe/{channelId} – Operational route
    Turns AutoRetrieveEmails off for the channel and its folders, then calls the Graph subscription service so active folder subscriptions are removed or cleared.

Subscribe example

POST /api/GraphWebhook/subscribe/{channelId}

200 OK

Unsubscribe example

POST /api/GraphWebhook/unsubscribe/{channelId}

200 OK

Fields and behavior

Graph webhook payload

GraphWebhookPayload

  • value
    Array of Microsoft Graph notification objects. The API iterates each item independently.

GraphNotification

  • subscriptionId
    Graph subscription identifier. Used as the primary lookup key for the subscribed folder.
  • resource
    Optional Graph resource path. Current fallback parsing expects /users/{mailbox}/mailFolders('{folderId}')/messages.
  • resourceData.id
    Graph message identifier supplied in the notification payload. It is accepted by the DTO but AnswerPal uses the subscription/folder context to enqueue folder import.

Stored folder subscription fields

  • GraphSubscriptionId
    Stored on channel folders after Microsoft Graph creates the subscription.
  • GraphSubscriptionExpiration
    Stored expiration timestamp used by the background renewal service.
  • AutoRetrieveEmails
    Channel-level and folder-level switch that controls whether Graph notifications can trigger automatic imports.

Access notes

Access model

  • GET /api/GraphWebhook and POST /api/GraphWebhook
    These callback routes are marked Public because Microsoft Graph must be able to validate and deliver notifications.
  • subscribe and unsubscribe
    These subscription-management routes are operational routes. Use them only from trusted admin tooling.
  • Most AnswerPal API endpoints
    Protected AnswerPal API endpoints use JWT Bearer authentication. The Webhooks callback is a documented exception because it is called by Microsoft Graph.

Common status codes

  • 200 OK
    Returned for successful validation, accepted notifications, empty callback bodies and successful subscribe/unsubscribe operations.
  • 400 Bad Request
    Returned by GET callback validation when no validationToken query value is provided.
  • 404 Not Found
    Returned by subscribe/unsubscribe when the channel does not exist, is deleted or has no email address.

For customer-configurable workflow actions, hook actions, hook documents and ticket-message runtime hooks, use the Hooks API Reference. For email channel settings, folder management, connection tests and channel translation routes, use the Channels API Reference.

No. The current Webhooks surface is for Microsoft Graph email notification callbacks and subscription toggles. AnswerPal event automation is documented on the Hooks endpoint page.

Microsoft Graph must be able to call the validation and notification callback without an AnswerPal user token. The routes are therefore marked Public.

The callback must resolve a channel folder, and both the folder and channel must have AutoRetrieveEmails enabled. If those conditions match, AnswerPal enqueues an automatic folder import job.

Table of Contents

AnswerPal: AI-powered customer service solutions to elevate your support and communication effortlessly.

Quick Links

Contact

For all support, sales, and partnership inquiries, email us at info@answerpal.eu

AnswerPal
Bisschoppenhoflaan 380
2100 Antwerp
Belgium

+32.36416685

BE 0862.692.858

Social Icons