Skip to main content

Webhooks API

Use webhooks to receive near real-time event change notifications from connected calendar providers.

When a user modifies an event in Google, Microsoft, Apple, or CalDAV, Connect can forward the normalized change payload to your configured project webhook URL after you subscribe the calendar via POST /subscribe-webhook.

This API lets you:

  • Subscribe a calendar to provider notifications
  • Unsubscribe an existing webhook channel
  • Receive normalized webhook payloads at your application webhook URL

Supported providers​

  • Google Calendar (google)
  • Microsoft Outlook (microsoft)
  • Apple Calendar (apple)
  • CalDAV (caldav)

Subscribe webhook​

Creates a webhook subscription for a specific calendar.

Endpoint: POST /subscribe-webhook

Authentication​

Requires Bearer token authentication:

Authorization: Bearer YOUR_ACCESS_TOKEN

Request parameters​

providerstringRequired

Provider name. Supported values: google, microsoft, apple, caldav.

calendarIdstringRequired

Calendar ID to subscribe.

channelIdstring

Optional custom subscription channel ID.

Default: Auto-generated
expirationnumber

Optional Unix timestamp in milliseconds. Provider-specific subscription expiration.

Default: Provider default

Response​

successboolean

true when subscription is created.

providerstring

Provider associated with this subscription.

subscriptionWebhookSubscription

Provider subscription details.

channelIdstring

Unique webhook channel/subscription identifier.

resourceIdstring

Provider resource identifier when available.

expirationstring

ISO 8601 expiration timestamp when available.

webhookUrlstring

Provider callback URL used by the subscription.

serverWebhookUrlstring

Mobiscroll Connect callback endpoint registered with the provider.

channelIdstring

Channel ID used for the subscription.

Error responses​

  • 400 - Missing required parameters, unsupported provider, or project webhook URL not configured
  • 401 - Unauthorized (invalid or missing Bearer token)
  • 500 - Internal server error

Example​

Create subscription
curl -X POST "https://connect.mobiscroll.com/api/subscribe-webhook" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "google",
    "calendarId": "work@company.com",
    "channelId": "my-channel-123"
  }'
Response
{
  "success": true,
  "provider": "google",
  "subscription": {
    "channelId": "my-channel-123",
    "resourceId": "resource-abc",
    "expiration": "2026-03-19T10:00:00.000Z",
    "webhookUrl": "https://your-connect-server/api/webhook-receiver/google"
  },
  "serverWebhookUrl": "https://your-connect-server/api/webhook-receiver/google",
  "channelId": "my-channel-123"
}

Unsubscribe webhook​

Removes an existing webhook subscription channel.

Endpoint: POST /unsubscribe-webhook

Authentication​

Requires Bearer token authentication.

Request parameters​

providerstringRequired

Provider name. Supported values: google, microsoft, apple, caldav.

channelIdstringRequired

Channel/subscription ID to remove.

resourceIdstring

Optional provider resource ID when applicable.

Default: undefined

Response​

successboolean

true when request is accepted and local mapping cleanup is completed.

messagestring

Additional status detail.

Error responses​

  • 400 - Missing parameters or unsupported provider
  • 401 - Unauthorized (invalid or missing Bearer token)
  • 500 - Internal server error

Example​

Unsubscribe channel
curl -X POST "https://connect.mobiscroll.com/api/unsubscribe-webhook" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "google",
    "channelId": "my-channel-123",
    "resourceId": "resource-abc"
  }'
Response
{
  "success": true,
  "message": "Webhook unsubscribed successfully"
}

Client webhook payload​

When a provider notification is processed, Mobiscroll Connect forwards a normalized payload to your configured project webhook URL.

providerstring

Notification source provider.

userIdstring

User ID in your system.

calendarIdstring

Calendar ID where changes were detected.

eventsArray<WebhookEvent>

Changed events list.

calendarIdstring

Calendar ID where the event belongs.

idstring

Event ID.

providerstring

Event provider.

titlestring

Event title.

descriptionstring

Event description/notes (optional).

lastModifiedstring

ISO 8601 timestamp of the last provider-side modification (optional).

startDate

Event start date/time.

endDate

Event end date/time.

allDayboolean

Indicates all-day event.

recurringEventIdstring

Recurring series master ID when this event is an instance (optional).

changeTypestring

One of created, updated, deleted.

colorstring

Optional event color.

locationstring

Optional event location.

attendeesArray<EventAttendee>

Optional attendee list.

emailstring

Attendee email.

statusstring

Response status: accepted, declined, tentative, or none.

organizerboolean

Indicates if attendee is organizer.

customobject

Optional custom key-value pairs.

conferenceobject

Optional conference metadata.

urlstring

Conference meeting URL.

autoGenerateboolean

If true, provider may auto-generate an online meeting link.

providerstring

Conference provider identifier.

dataobject

Provider-specific conference payload.

availabilitystring

Optional availability: busy or free.

privacystring

Optional privacy: public, private, or confidential.

statusstring

Optional event status: confirmed, tentative, or cancelled.

linkstring

Optional provider event link.

originalobject

Provider-native event object.

changeTypestring

Overall change summary: created, updated, deleted, or mixed.

timestampstring

ISO 8601 processing timestamp.

metadataobject

Additional webhook metadata.

channelIdstring

Subscription channel ID.

eventCountnumber

Number of events in this delivery.

isInitialSyncboolean

Indicates initial/sync-state delivery when applicable.

Example delivery​

Delivered to your webhook URL
{
  "provider": "google",
  "userId": "user-123",
  "calendarId": "work@company.com",
  "events": [
    {
      "id": "event-abc",
      "provider": "google",
      "calendarId": "work@company.com",
      "title": "Product review",
      "description": "Quarterly review",
      "lastModified": "2026-03-10T09:00:00.000Z",
      "start": "2026-03-12T09:00:00.000Z",
      "end": "2026-03-12T10:00:00.000Z",
      "allDay": false,
      "recurringEventId": "series-master-id",
      "color": "#9fc6e7",
      "location": "Office / Meeting room",
      "attendees": [
        {
          "email": "user@example.com",
          "status": "accepted",
          "organizer": true
        }
      ],
      "custom": {
        "yourCustomKey": "yourCustomValue"
      },
      "conference": {
        "url": "https://meet.example.com/abc",
        "provider": "google-meet"
      },
      "availability": "busy",
      "privacy": "private",
      "status": "confirmed",
      "link": "https://provider-event-link",
      "changeType": "updated",
      "original": {}
    }
  ],
  "changeType": "updated",
  "timestamp": "2026-03-12T09:01:12.000Z",
  "metadata": {
    "channelId": "sub-123",
    "eventCount": 1,
    "isInitialSync": false
  }
}

Setup requirements​

  1. Configure Webhook URL in your Connect application settings. See Application setup.
  2. Ensure your webhook endpoint is public, reachable, and returns 2xx quickly.
  3. Keep endpoint handling idempotent and tolerant of out-of-order notifications.

Operational notes​

  • Delivery forwarding to your webhook URL is best-effort and should be handled with idempotent processing on your side.
  • Provider-side notifications may be emitted for changes regardless of where the change originated.
  • Connect applies built-in echo/loop filtering for very recent API-originated changes (short-lived in-memory dedup window, currently 30 seconds), so webhook echoes for your own immediate POST /event / PUT /event updates are suppressed in the common case.
  • In distributed or multi-instance setups, add an application-level origin marker in custom (for example custom.source = "my-system") and ignore matching webhook events as an additional loop-prevention safeguard.
  • For Apple, event change detection is based on periodic synchronization (polled every 5 minutes) rather than provider-native push.
  • For CalDAV, event change detection is based on periodic synchronization rather than provider-native push.
  • A single delivery may contain multiple event changes and return changeType: "mixed".
  • When notifications are filtered out, no events may be delivered in that callback cycle.