GraphApi.Subscriptions (GraphApi v1.0.0-rc.1)

Copy Markdown View Source

Operations on the /subscriptions resource.

Subscriptions allow your application to receive webhook notifications when data changes in Microsoft Graph. You create a subscription for a specific resource (e.g., users, messages, events) and Microsoft Graph sends POST requests to your notification URL when changes occur.

Examples

# Create a subscription
{:ok, sub} = GraphApi.Subscriptions.create(%{
  "changeType" => "created,updated,deleted",
  "notificationUrl" => "https://example.com/webhook",
  "resource" => "users",
  "expirationDateTime" => "2025-04-01T00:00:00Z",
  "clientState" => "my-secret-state"
})

# List active subscriptions
{:ok, %{"value" => subs}} = GraphApi.Subscriptions.list()

# Renew before expiration
{:ok, renewed} = GraphApi.Subscriptions.renew(sub["id"], %{
  "expirationDateTime" => "2025-05-01T00:00:00Z"
})

# Clean up
:ok = GraphApi.Subscriptions.delete(sub["id"])

Summary

Functions

create(attrs, opts \\ [])

Creates a new subscription.

create_query(attrs, opts \\ [])

Batch query variant of create/2.

delete(subscription_id, opts \\ [])

Deletes a subscription.

delete_query(subscription_id, opts \\ [])

Batch query variant of delete/2.

get(subscription_id, opts \\ [])

Gets a subscription by ID.

get_query(subscription_id, opts \\ [])

Batch query variant of get/2.

list(opts \\ [])

Lists active subscriptions.

list_query(opts \\ [])

Batch query variant of list/1.

renew(subscription_id, attrs, opts \\ [])

Renews (updates) a subscription, typically to extend its expiration.

renew_query(subscription_id, attrs, opts \\ [])

Batch query variant of renew/3.

Functions

create(attrs, opts \\ [])

@spec create(
  map(),
  keyword()
) :: {:ok, map()} | {:error, term()}

Creates a new subscription.

Required fields

  • "changeType" — Comma-separated: "created", "updated", "deleted"
  • "notificationUrl" — HTTPS endpoint that will receive notifications
  • "resource" — Resource path to watch (e.g., "users", "me/messages")
  • "expirationDateTime" — ISO 8601 datetime for subscription expiry

Optional fields

  • "clientState" — Secret string included in each notification for validation
  • "latestSupportedTlsVersion" — Minimum TLS version

create_query(attrs, opts \\ [])

@spec create_query(
  map(),
  keyword()
) :: GraphApi.Batch.Request.t()

Batch query variant of create/2.

delete(subscription_id, opts \\ [])

@spec delete(
  String.t(),
  keyword()
) :: :ok | {:error, term()}

Deletes a subscription.

delete_query(subscription_id, opts \\ [])

@spec delete_query(
  String.t(),
  keyword()
) :: GraphApi.Batch.Request.t()

Batch query variant of delete/2.

get(subscription_id, opts \\ [])

@spec get(
  String.t(),
  keyword()
) :: {:ok, map()} | {:error, term()}

Gets a subscription by ID.

get_query(subscription_id, opts \\ [])

@spec get_query(
  String.t(),
  keyword()
) :: GraphApi.Batch.Request.t()

Batch query variant of get/2.

list(opts \\ [])

@spec list(keyword()) :: {:ok, map()} | {:error, term()}

Lists active subscriptions.

list_query(opts \\ [])

@spec list_query(keyword()) :: GraphApi.Batch.Request.t()

Batch query variant of list/1.

renew(subscription_id, attrs, opts \\ [])

@spec renew(String.t(), map(), keyword()) :: {:ok, map()} | :ok | {:error, term()}

Renews (updates) a subscription, typically to extend its expiration.

Examples

GraphApi.Subscriptions.renew("sub-id", %{
  "expirationDateTime" => "2025-05-01T00:00:00Z"
})

renew_query(subscription_id, attrs, opts \\ [])

@spec renew_query(String.t(), map(), keyword()) :: GraphApi.Batch.Request.t()

Batch query variant of renew/3.