Rediger

Connector Trigger for Azure Functions

Azure Functions provides trigger and binding extensions that integrate with various services, primarily Azure services. The Connector Extension expands these integrations to a much wider selection of services, including business systems and data platforms.

For example, use the Connector Trigger to run a function when a new email arrives in Office 365 Outlook, a file is created in SharePoint, or a record changes in Salesforce. The trigger receives events from a managed connector in Azure Connector Namespace. To explore the available managed connectors, see the connectors reference.

For more information about managed connectors, when to use them, and feature availability, see Use managed connectors in Azure Functions.

Note

The Connector Trigger isn't currently supported for this language.

Delivery modes

Managed connectors support two delivery modes:

  • Polling: The Functions host connects outbound to the Connector Namespace to receive events. Set deliveryMode: 'Poll', and supply connection and triggerConfigName in the registration options.
  • Webhook: The Connector Namespace sends events to the extension's callback endpoint. Webhook is the default when you omit deliveryMode.

Both modes support named helpers such as connectors.office365.onNewEmail and the generic connectorTrigger helper. For help choosing a mode, see Choose a delivery mode.

Get started

Follow the setup path for your delivery mode:

  1. Install the Node.js packages and configure the extension bundle.
  2. Create or reuse a namespace and connection, and create a polling trigger configuration.
  3. Get the polling endpoint.
  4. Configure caller credentials, connection access, and local or deployed settings.
  5. Use a polling example below, matching its connection and triggerConfigName values to your settings.

Polling doesn't require a public callback endpoint or system key. For webhook delivery, the destination function and callback endpoint must be ready before you create the trigger configuration.

Delivery modes

Managed connectors support two delivery modes:

  • Polling: The Functions host connects outbound to the Connector Namespace to receive events. Set delivery_mode=func.DeliveryMode.POLL, and supply connection and trigger_config_name on @app.connector_trigger.
  • Webhook: The Connector Namespace sends events to the extension's callback endpoint. Webhook is the default when you omit delivery_mode on @app.connector_trigger.

For help choosing a mode, see Choose a delivery mode.

Get started

Follow the setup path for your delivery mode:

  1. Install the Python packages and configure the extension bundle.
  2. Create or reuse a namespace and connection, and create a polling trigger configuration.
  3. Get the polling endpoint.
  4. Configure caller credentials, connection access, and local or deployed settings.
  5. Use a polling example below, matching its connection and trigger_config_name values to your settings.

Polling doesn't require a public callback endpoint or system key. For webhook delivery, the destination function and callback endpoint must be ready before you create the trigger configuration.

Delivery modes

Managed connectors support two delivery modes:

  • Polling: The Functions host connects outbound to the Connector Namespace to receive events. Set DeliveryMode = ConnectorTriggerDeliveryMode.Poll, and add the connection settings and trigger configuration on [ConnectorTrigger].
  • Webhook: The Connector Namespace sends events to the extension's callback endpoint. Webhook is the default when you omit DeliveryMode on the [ConnectorTrigger] attribute.

For help choosing a mode, see Choose a delivery mode.

Get started

Follow the setup path for your delivery mode:

  1. Install the extension.
  2. Create or reuse a namespace and connection, and create a polling trigger configuration.
  3. Get the polling endpoint.
  4. Configure caller credentials, connection access, and local or deployed settings.
  5. Use an example below, matching its Connection and TriggerConfigName values to your settings.

Polling doesn't require a public callback endpoint or system key. For webhook delivery, the destination function and callback endpoint must be ready before you create the trigger configuration.

Examples

The Office 365 Outlook and SharePoint Online examples use strongly typed payloads from the Azure Connectors SDK. For connector operations that don't yet have strongly typed payloads, bind to string to receive the raw JSON payload. These examples intentionally log only basic payload information to stay focused on how to define connector-triggered functions. Replace the logging with your application's processing logic.

To find which connector operations support strongly typed payloads for .NET, see Operations to Azure Functions signature mapping.

The polling delivery mode also supports optional properties on the [ConnectorTrigger] attribute. For descriptions, supported values, and defaults, see polling attribute properties.

Office 365 Outlook

The following example runs when a new email arrives in the configured Office 365 Outlook mailbox:

This example receives batches of up to four connector events, each containing one email, and uses ConnectorEvent<T> to access each event's payload and MessageId.

using Microsoft.Azure.Functions.Worker;
using Microsoft.Azure.Functions.Worker.Extensions.Connector;
using Microsoft.Extensions.Logging;
using Azure.Connectors.Sdk.Office365.Models;

namespace Office365App;

public sealed class O365Functions(ILogger<O365Functions> logger)
{
    [Function("OnNewEmail")]
    public void OnNewEmail(
        [ConnectorTrigger(
            DeliveryMode = ConnectorTriggerDeliveryMode.Poll,
            Connection = "ConnectorNamespace",
            TriggerConfigName = "%OnNewEmailTriggerConfigName%",
            IsBatched = true,
            MaxBatchSize = 4,
            TargetPendingEventThreshold = 16)]
        ConnectorEvent<Office365OnNewEmailTriggerPayload>[] emails)
    {
        foreach (var email in emails)
        {
            var messageCount = email.Data.Body?.Value?.Count ?? 0;
            logger.LogInformation(
                "Poll event {MessageId}: received {MessageCount} new email message(s).",
                email.MessageId,
                messageCount);
        }
    }
}

For local development, include the connection settings and trigger configuration name in the Values section of local.settings.json:

{
  "ConnectorNamespace__pollingEndpoint": "https://<connector-namespace-host>",
  "OnNewEmailTriggerConfigName": "<polling-trigger-config-name>"
}

The attribute properties refer to these settings:

  • Connection = "ConnectorNamespace" identifies the settings prefix. The extension reads the polling endpoint from ConnectorNamespace__pollingEndpoint. For how to get the endpoint and information about the required credentials and access policies, see Polling endpoint.
  • TriggerConfigName = "%OnNewEmailTriggerConfigName%" resolves the value of the OnNewEmailTriggerConfigName setting. Set its value to the name of the polling trigger configuration in your Connector Namespace.

The prefix and setting names are illustrative; if you change them, update both the attribute properties and the settings to match. For a deployed function app, add the same settings to the function app's app settings instead of local.settings.json.

The Office365OnNewEmailTriggerPayload type is defined in the Azure.Connectors.Sdk.Office365.Models namespace.

For the complete code sample, including infrastructure and trigger registration, see Office 365 Outlook triggers for .NET.

SharePoint Online

The following example runs when a file is created in the configured SharePoint Online document library:

This example receives one connector event containing one file per invocation (the default) and uses ConnectorEvent<T> to access its payload and MessageId.

using Microsoft.Azure.Functions.Worker;
using Microsoft.Azure.Functions.Worker.Extensions.Connector;
using Microsoft.Extensions.Logging;
using Azure.Connectors.Sdk.SharePointOnline.Models;

namespace SharePointApp;

public sealed class SharePointFunctions(ILogger<SharePointFunctions> logger)
{
    [Function("OnNewFile")]
    public void OnNewFile(
        [ConnectorTrigger(
            DeliveryMode = ConnectorTriggerDeliveryMode.Poll,
            Connection = "ConnectorNamespace",
            TriggerConfigName = "%OnNewFileTriggerConfigName%")]
        ConnectorEvent<SharePointOnlineOnNewFileItemsTriggerPayload> file)
    {
        var fileCount = file.Data.Body?.Value?.Count ?? 0;
        logger.LogInformation(
            "Poll event {MessageId}: received {FileCount} new SharePoint file(s).",
            file.MessageId,
            fileCount);
    }
}

For local development, include these values in the Values object in local.settings.json:

{
  "ConnectorNamespace__pollingEndpoint": "https://<connector-namespace-host>",
  "OnNewFileTriggerConfigName": "<polling-trigger-config-name>"
}

The attribute properties refer to these settings:

  • Connection = "ConnectorNamespace" identifies the settings prefix. The extension reads the polling endpoint from ConnectorNamespace__pollingEndpoint. For how to get the endpoint and information about the required credentials and access policies, see Polling endpoint.
  • TriggerConfigName = "%OnNewFileTriggerConfigName%" resolves the value of the OnNewFileTriggerConfigName setting. Set its value to the name of the SharePoint polling trigger configuration in your Connector Namespace.

The prefix and setting names are illustrative; if you change them, update both the attribute properties and the settings to match. For a deployed function app, add the same settings to the function app's app settings instead of local.settings.json.

The SharePointOnlineOnNewFileItemsTriggerPayload type is defined in the Azure.Connectors.Sdk.SharePointOnline.Models namespace.

For the complete code sample, including infrastructure and trigger registration, see SharePoint Online triggers for .NET.

Connector without a strongly typed payload

Some connector events don't yet have a strongly typed .NET payload. The following example runs when a new message is added to a Microsoft Teams chat or channel. Polling uses ConnectorEvent<string> to receive the raw JSON payload with delivery metadata; webhook delivery binds directly to string:

This example receives one connector event per invocation (default) and uses ConnectorEvent<string> to access its JSON payload and MessageId.

using Microsoft.Azure.Functions.Worker;
using Microsoft.Azure.Functions.Worker.Extensions.Connector;
using Microsoft.Extensions.Logging;

namespace TeamsApp;

public sealed class TeamsFunctions(ILogger<TeamsFunctions> logger)
{
    [Function("OnNewTeamsMessage")]
    public void OnNewTeamsMessage(
        [ConnectorTrigger(
            DeliveryMode = ConnectorTriggerDeliveryMode.Poll,
            Connection = "ConnectorNamespace",
            TriggerConfigName = "%OnNewTeamsMessageTriggerConfigName%")]
        ConnectorEvent<string> message)
    {
        logger.LogInformation(
            "Poll event {MessageId}: received a Teams payload of {PayloadLength} characters.",
            message.MessageId,
            message.Data.Length);
    }
}

For local development, include these values in the Values object in local.settings.json:

{
  "ConnectorNamespace__pollingEndpoint": "https://<connector-namespace-host>",
  "OnNewTeamsMessageTriggerConfigName": "<polling-trigger-config-name>"
}

The attribute properties refer to these settings:

  • Connection = "ConnectorNamespace" identifies the settings prefix. The extension reads the polling endpoint from ConnectorNamespace__pollingEndpoint. For how to get the endpoint and information about the required credentials and access policies, see Polling endpoint.
  • TriggerConfigName = "%OnNewTeamsMessageTriggerConfigName%" resolves the value of the OnNewTeamsMessageTriggerConfigName setting. Set its value to the name of the Teams polling trigger configuration in your Connector Namespace.

The prefix and setting names are illustrative; if you change them, update both the attribute properties and the settings to match. For a deployed function app, add the same settings to the function app's app settings instead of local.settings.json.

For the complete code sample, including infrastructure and trigger registration, see Generic connector triggers for .NET.

Connector event mappings

The operation name is defined by the managed connector. You choose the function name in your code. The polling and webhook examples use the same event, operation, and function names:

Connector event Operation name Function name
New Office 365 Outlook email OnNewEmailV3 OnNewEmail
New SharePoint Online file GetOnNewFileItems OnNewFile
New Microsoft Teams chat or channel message WebhookNewMessageTrigger OnNewTeamsMessage

Webhook payloads can contain multiple items, depending on the trigger configuration.

Polling delivery always enables splitOn, so each queued event contains one split item. However, the polling mode can group events into one function invocation by setting IsBatched = true. For batching configuration, see Attributes.

Binding types

For .NET isolated worker functions, both delivery modes support these parameter types:

Type Description
string Receives the event body as raw JSON. Use this type when a strongly typed SDK model isn't available or when you want to deserialize the payload yourself.
Connector SDK model Deserializes the JSON event body into an operation-specific model from Azure.Connectors.Sdk, such as Office365OnNewEmailTriggerPayload or SharePointOnlineOnNewFileItemsTriggerPayload.
JSON-deserializable POCO Deserializes the JSON event body into a .NET type whose shape matches the connector payload by using the configured worker serializer.
ConnectorEvent<T> Wraps a supported payload type in Data. MessageId contains the delivery identifier for polling and is null for webhook delivery.

Array parameters

Array parameters have different meanings in each delivery mode.

For polling, IsBatched determines the function parameter shape, where T is a supported event payload type:

IsBatched Function parameter type
false (default) T or ConnectorEvent<T>
true T[] or ConnectorEvent<T>[], even when MaxBatchSize = 1

Set MaxBatchSize to a value from 1 through 32; without batching, the effective batch size must be 1. Batch size counts connector events, not items within an event's payload. Batching doesn't change the payload type inside each event. An SDK payload's Body.Value collection is separate from the outer array of events supplied to a batched invocation.

For webhook, use T[] to deserialize a single callback's JSON array body into an array of payload items. This isn't a batch of separately delivered events. Webhook delivery processes one callback per invocation; IsBatched applies only to polling.

Examples

The Node.js connector extension provides typed contexts for the Office 365 Outlook, SharePoint Online, and Microsoft Teams operations shown in this section. These examples intentionally log only basic payload information to stay focused on how to define Connector-triggered functions. Replace the logging with your application's processing logic.

To find which connector operations support strongly typed payloads for JavaScript and TypeScript, see the Node.js connector extension reference.

Office 365 Outlook

The following example runs when a new email arrives in the configured Office 365 Outlook mailbox:

This example receives up to four connector events per invocation. The helper supplies the emails from those events as one list.

import { InvocationContext } from '@azure/functions';
import {
    connectors,
    EmailTriggerContext,
} from '@azure/functions-extensions-connectors';

connectors.office365.onNewEmail('OnNewEmail', {
    deliveryMode: 'Poll',
    connection: 'ConnectorNamespace',
    triggerConfigName: '%OnNewEmailTriggerConfigName%',
    cardinality: 'many',
    maxBatchSize: 4,
    targetPendingEventThreshold: 16,
    handler: async (
        context: EmailTriggerContext,
        invocationContext: InvocationContext,
    ) => {
        invocationContext.log(
            `Received ${context.emails.length} new email message(s).`,
        );
    },
});

The EmailTriggerContext type exposes the messages as a typed emails array.

For additional examples, see Office 365 Outlook triggers for TypeScript.

SharePoint Online

The following example runs when a file is created in the configured SharePoint Online document library:

This example receives one connector event per invocation, the default. The helper supplies its file-property records as a list.

import { InvocationContext } from '@azure/functions';
import {
    connectors,
    SharepointItemTriggerContext,
} from '@azure/functions-extensions-connectors';

connectors.sharepoint.onNewFileItems('OnSharepointNewFile', {
    deliveryMode: 'Poll',
    connection: 'ConnectorNamespace',
    triggerConfigName: '%OnSharepointNewFileTriggerConfigName%',
    handler: async (
        context: SharepointItemTriggerContext,
        invocationContext: InvocationContext,
    ) => {
        invocationContext.log(
            `Received ${context.records.length} new SharePoint file(s).`,
        );
    },
});

The SharepointItemTriggerContext type exposes file-property records through records for the GetOnNewFileItems operation. The helper preserves the fields supplied by the connector without converting them into a fixed file schema. For additional examples, see SharePoint Online triggers for TypeScript.

Microsoft Teams

The following example runs when a new message is added to a Microsoft Teams channel:

This example receives one connector event per invocation, the default. The helper supplies its message payload as a list.

import { InvocationContext } from '@azure/functions';
import {
    ChannelMessageTriggerContext,
    connectors,
} from '@azure/functions-extensions-connectors';

connectors.teams.onNewChannelMessage('OnNewChannelMessage', {
    deliveryMode: 'Poll',
    connection: 'ConnectorNamespace',
    triggerConfigName: '%OnNewTeamsMessageTriggerConfigName%',
    handler: async (
        context: ChannelMessageTriggerContext,
        invocationContext: InvocationContext,
    ) => {
        invocationContext.log(
            `Received ${context.messages.length} new Teams message(s).`,
        );
    },
});

The ChannelMessageTriggerContext type exposes the messages as a typed messages array.

For additional examples, see Microsoft Teams triggers for TypeScript.

Generic connector payload

Use the generic helper when an operation doesn't have a named registration. Access context.rawPayload when your code needs to process the original payload itself.

This example receives one connector event per invocation, the default. The helper supplies its payload items as a list.

import { InvocationContext } from '@azure/functions';
import {
    connectorTrigger,
    ConnectorTriggerContext,
} from '@azure/functions-extensions-connectors';

connectorTrigger('OnConnectorEvent', {
    deliveryMode: 'Poll',
    connection: 'ConnectorNamespace',
    triggerConfigName: '%GenericTriggerConfigName%',
    handler: async (
        context: ConnectorTriggerContext,
        invocationContext: InvocationContext,
    ) => {
        invocationContext.log(`Received ${context.items.length} payload item(s).`);
    },
});

The generic context defaults its item type to unknown. Validate items before accessing operation-specific properties. context.rawPayload preserves the parsed input before normalization, including the outer event array for batched polling.

Examples

The Node.js connector extension provides connector-specific contexts for the Office 365 Outlook, SharePoint Online, and Microsoft Teams operations shown in this section. These examples intentionally log only basic payload information to stay focused on how to define Connector-triggered functions. Replace the logging with your application's processing logic.

To find which connector operations support strongly typed payloads for JavaScript and TypeScript, see the Node.js connector extension reference.

Office 365 Outlook

The following example runs when a new email arrives in the configured Office 365 Outlook mailbox:

This example receives up to four connector events per invocation. The helper supplies the emails from those events as one list.

const {
    connectors,
} = require('@azure/functions-extensions-connectors');

connectors.office365.onNewEmail('OnNewEmail', {
    deliveryMode: 'Poll',
    connection: 'ConnectorNamespace',
    triggerConfigName: '%OnNewEmailTriggerConfigName%',
    cardinality: 'many',
    maxBatchSize: 4,
    targetPendingEventThreshold: 16,
    handler: async (context, invocationContext) => {
        invocationContext.log(
            `Received ${context.emails.length} new email message(s).`,
        );
    },
});

The handler context exposes the messages through the emails array.

SharePoint Online

The following example runs when a file is created in the configured SharePoint Online document library:

This example receives one connector event per invocation, the default. The helper supplies its file-property records as a list.

const {
    connectors,
} = require('@azure/functions-extensions-connectors');

connectors.sharepoint.onNewFileItems('OnSharepointNewFile', {
    deliveryMode: 'Poll',
    connection: 'ConnectorNamespace',
    triggerConfigName: '%OnSharepointNewFileTriggerConfigName%',
    handler: async (context, invocationContext) => {
        invocationContext.log(
            `Received ${context.records.length} new SharePoint file(s).`,
        );
    },
});

The handler context exposes file-property records through records for the GetOnNewFileItems operation. The helper preserves the fields supplied by the connector without converting them into a fixed file schema.

Microsoft Teams

The following example runs when a new message is added to a Microsoft Teams channel:

This example receives one connector event per invocation, the default. The helper supplies its message payload as a list.

const {
    connectors,
} = require('@azure/functions-extensions-connectors');

connectors.teams.onNewChannelMessage('OnNewChannelMessage', {
    deliveryMode: 'Poll',
    connection: 'ConnectorNamespace',
    triggerConfigName: '%OnNewTeamsMessageTriggerConfigName%',
    handler: async (context, invocationContext) => {
        invocationContext.log(
            `Received ${context.messages.length} new Teams message(s).`,
        );
    },
});

The handler context exposes the messages through the messages array.

Generic connector payload

Use the generic helper when an operation doesn't have a named registration. Access context.rawPayload when your code needs to process the original payload itself.

This example receives one connector event per invocation, the default. The helper supplies its payload items as a list.

const {
    connectorTrigger,
} = require('@azure/functions-extensions-connectors');

connectorTrigger('OnConnectorEvent', {
    deliveryMode: 'Poll',
    connection: 'ConnectorNamespace',
    triggerConfigName: '%GenericTriggerConfigName%',
    handler: async (context, invocationContext) => {
        invocationContext.log(`Received ${context.items.length} payload item(s).`);
    },
});

Validate items before accessing operation-specific properties. context.rawPayload preserves the parsed input before normalization, including the outer event array for batched polling.

Local polling settings

Add the polling endpoint and trigger configuration names to local.settings.json:

{
  "IsEncrypted": false,
  "Values": {
    "ConnectorNamespace__pollingEndpoint": "https://<connector-namespace-host>",
    "OnNewEmailTriggerConfigName": "<outlook-polling-trigger-config-name>",
    "OnSharepointNewFileTriggerConfigName": "<sharepoint-polling-trigger-config-name>",
    "OnNewTeamsMessageTriggerConfigName": "<teams-polling-trigger-config-name>",
    "GenericTriggerConfigName": "<generic-polling-trigger-config-name>"
  }
}

The examples' connection: 'ConnectorNamespace' value identifies the settings prefix. Each triggerConfigName expression resolves to its corresponding app setting. For deployed settings and connection permissions, see Polling authentication.

For another example of polling registration, see the Node.js polling sample.

Examples

The Office 365 Outlook and SharePoint Online examples use converters provided by azurefunctions-extensions-connectors. The generic example receives raw JSON without an SDK annotation. These examples log only basic payload information; replace the logging with your application's processing logic.

To find which connector operations support strongly typed payloads for Python, see Key concepts in the Python connector extension.

Office 365 Outlook

The following example runs when a new email arrives in the configured Office 365 Outlook mailbox:

This example receives up to four connector events per invocation. The converter supplies the emails from those events as one list.

import logging

import azure.functions as func
import azurefunctions.extensions.connectors.office365 as office365

app = func.FunctionApp()


@app.function_name(name="OnNewEmail")
@app.connector_trigger(
    arg_name="emails",
    delivery_mode=func.DeliveryMode.POLL,
    connection="ConnectorNamespace",
    trigger_config_name="%OnNewEmailTriggerConfigName%",
    cardinality=func.Cardinality.MANY,
    max_batch_size=4,
    target_pending_event_threshold=16,
)
def on_new_email(
    emails: list[office365.GraphClientReceiveMessage],
) -> None:
    logging.info(
        "Received %s new email message(s).",
        len(emails),
    )

The GraphClientReceiveMessage binding supports the OnNewEmailV3 operation. For complete code, infrastructure, and trigger registration for both modes, see Office 365 Outlook triggers for Python.

SharePoint Online

The following example runs when a file is created in the configured SharePoint Online document library:

This example receives one connector event per invocation, the default. The converter supplies its file-property records as a list.

import logging

import azure.functions as func
import azurefunctions.extensions.connectors.sharepointonline as sharepoint

app = func.FunctionApp()


@app.function_name(name="OnSharepointNewFile")
@app.connector_trigger(
    arg_name="files",
    delivery_mode=func.DeliveryMode.POLL,
    connection="ConnectorNamespace",
    trigger_config_name="%OnSharepointNewFileTriggerConfigName%",
)
def on_sharepoint_new_file(files: list[sharepoint.Item]) -> None:
    logging.info(
        "Received %s new SharePoint file(s).",
        len(files),
    )

The Item binding supports the GetOnNewFileItems operation and preserves file properties in dynamic_properties. For complete code, infrastructure, and trigger registration for both modes, see SharePoint Online triggers for Python.

Generic connector payload

Use the azure-functions library to receive events as raw JSON strings when an operation doesn't have a supported typed converter, or when you want to parse the JSON yourself.

This example receives one connector event per invocation, the default, as a raw JSON string.

import logging

import azure.functions as func

app = func.FunctionApp()


@app.function_name(name="OnConnectorEvent")
@app.connector_trigger(
    arg_name="payload",
    delivery_mode=func.DeliveryMode.POLL,
    connection="ConnectorNamespace",
    trigger_config_name="%GenericTriggerConfigName%",
)
def on_connector_event(payload: str) -> None:
    logging.info("Received a connector event.")

For complete examples, see Generic connector triggers for Python.

For local polling, define the endpoint and trigger configuration names under Values in local.settings.json:

{
  "IsEncrypted": false,
  "Values": {
    "ConnectorNamespace__pollingEndpoint": "https://<connector-namespace-host>",
    "OnNewEmailTriggerConfigName": "<outlook-polling-trigger-config-name>",
    "OnSharepointNewFileTriggerConfigName": "<sharepoint-polling-trigger-config-name>",
    "GenericTriggerConfigName": "<generic-polling-trigger-config-name>"
  }
}

The examples' connection="ConnectorNamespace" value identifies the settings prefix. Each trigger_config_name expression resolves to its corresponding app setting. For deployed settings and connection permissions, see Polling authentication.

Binding types

Both delivery modes support the following registration and payload shapes:

Registration Handler input
app.connectorTrigger from @azure/functions Receives the original trigger input without helper normalization. The TypeScript input type defaults to unknown; for batched polling, use an array type such as unknown[].
connectorTrigger from @azure/functions-extensions-connectors Receives a ConnectorTriggerContext<T> with normalized payload and items, parsed rawPayload, and toJSON() serialization. The TypeScript item type defaults to unknown.
Named helpers such as connectors.office365.onNewEmail Receive the normalized context with a named array, such as emails, records, or messages, that aliases items. TypeScript infers the supported SDK item type.

Helpers accept object inputs or JSON strings. They normalize { body: item } and { body: { value: [...] } } envelopes. For batched polling, they flatten the outer array of envelopes and their payload items into one items array, preserving order. rawPayload retains the parsed input before normalization, including the outer event array.

Set cardinality: 'many' to enable invocation batching. An array in the context or a TypeScript array type alone doesn't enable batching. maxBatchSize counts connector events, not items in the normalized array. Each webhook invocation handles one callback, which can contain multiple payload items.

TypeScript types describe the expected payload but don't validate or transform operation-specific fields at runtime. Validate the payload before accessing properties when its shape isn't known. For supported typed registrations and SDK payload types, see the Node.js connector extension reference.

Binding types

The Connector trigger supports these Python parameter types:

Type Description
str Receives the event body as a JSON string.
dict Accepted as an annotation, but the raw converter doesn't parse JSON strings into dictionaries. To parse raw JSON, bind to str and use json.loads.
bytes Receives the event body as raw bytes.
typing.List[str] or typing.List[bytes] Receives separately delivered connector events as a list when polling uses cardinality=func.Cardinality.MANY. Import List from typing for these annotations.
Supported Connector SDK annotation Uses a converter registered by azurefunctions-extensions-connectors to deserialize the payload into a list of operation-specific SDK models.

For SDK bindings, annotate the parameter with the supported binding type or a list of that type, such as list[office365.GraphClientReceiveMessage]. The supported SDK bindings return lists for both single-event and batched invocations. For batched polling, the converter flattens the transport events and their payload items into one list.

Set cardinality=func.Cardinality.MANY on the decorator to enable invocation batching. A list annotation alone doesn't enable batching. The batch-size setting counts connector events, not items within an event's payload or the number of models in the returned list.

Connection access and callback authorization are separate. The Connector Namespace handles its own access to the managed connector connection automatically. Configure the function app's access according to its delivery mode.

Polling mode

Attributes

The ConnectorTrigger attribute supports the following properties when DeliveryMode is set to ConnectorTriggerDeliveryMode.Poll:

Property Required Default Description
DeliveryMode Yes, for polling ConnectorTriggerDeliveryMode.Webhook Set to ConnectorTriggerDeliveryMode.Poll to use polling.
Connection Yes null Identifies the configuration prefix for the Connector Namespace polling endpoint and identity settings. For example, "ConnectorNamespace" selects ConnectorNamespace__pollingEndpoint.
TriggerConfigName Yes null The name of the polling trigger configuration in the Connector Namespace. Supply the name directly or use an app setting expression such as "%OnNewEmailTriggerConfigName%".
IsBatched No false Whether each invocation receives a batch of connector events. When false, each invocation receives one event. Set to true and use an array parameter to receive batches. Batches are processed one at a time per listener.
MaxBatchSize No 1 Maximum connector events per invocation, from 1 through 32. When omitted or set to 0, uses the host's defaultMaxBatchSize setting, which defaults to 1 unless configured otherwise in host.json. The effective batch size must be 1 when IsBatched is false.
MaxConcurrentCalls No 16 Maximum concurrent single-event processing tasks per listener on one instance, including preparation, invocation, and acknowledgement. Must be non-negative. When omitted or set to 0, uses the host's defaultMaxConcurrentCalls setting, which defaults to 16 unless configured otherwise in host.json. Applies only when IsBatched is false. Batched invocations process one batch at a time per listener.
TargetPendingEventThreshold No 16 Desired number of pending connector events per instance for target-based scaling. Must be non-negative. When omitted or set to 0, uses the host's defaultTargetPendingEventThreshold setting, which defaults to 16 unless configured otherwise in host.json. The runtime can override this scaling target. This property doesn't change batch size or invocation concurrency.

For app-wide defaults, see Polling host.json settings. Batch size counts connector events, not items within an event's payload.

Polling decorators

Set delivery_mode=func.DeliveryMode.POLL on @app.connector_trigger and configure the polling connection and trigger configuration:

Parameter Required Default Description
arg_name Yes None Identifies the function parameter that receives the payload.
delivery_mode Yes, for polling func.DeliveryMode.WEBHOOK Set to func.DeliveryMode.POLL to use polling. The strings "Poll" and "Webhook" are also supported.
connection Yes None Identifies the settings prefix for the polling endpoint and identity settings. For example, "ConnectorNamespace" selects ConnectorNamespace__pollingEndpoint.
trigger_config_name Yes None Identifies the polling trigger configuration. Supply the name directly or use an app setting expression such as "%OnNewEmailTriggerConfigName%".
cardinality No func.Cardinality.ONE Set to func.Cardinality.MANY or "many" to enable invocation batching. Batched invocations are processed one at a time per listener.
max_batch_size No Host default: 1 Maximum connector events per invocation, from 1 through 32. When omitted or set to 0, uses defaultMaxBatchSize from host.json. Without batching, the effective batch size must be 1.
max_concurrent_calls No Host default: 16 Maximum concurrent single-event processing tasks per listener on one instance. When omitted or set to 0, uses defaultMaxConcurrentCalls from host.json. Must be non-negative. Doesn't apply to batched invocations.
target_pending_event_threshold No Host default: 16 Target pending events per instance for target-based scaling. When omitted or set to 0, uses defaultTargetPendingEventThreshold from host.json. Must be non-negative. Doesn't change batch size or invocation concurrency; the runtime can override the scaling target.

For app-wide defaults, see Polling host.json settings. For parameter shapes and SDK annotations, see Binding types.

Polling registration options

Set deliveryMode: 'Poll' on a named helper, the generic connectorTrigger helper, or app.connectorTrigger, and configure the polling connection and trigger configuration:

Option Required Default Description
deliveryMode Yes, for polling 'Webhook' Set to 'Poll' to use polling.
connection Yes None Identifies the settings prefix for the polling endpoint and identity settings. For example, 'ConnectorNamespace' selects ConnectorNamespace__pollingEndpoint.
triggerConfigName Yes None Identifies the polling trigger configuration. Supply the name directly or use an app setting expression such as '%OnNewEmailTriggerConfigName%'.
cardinality No 'one' Set to 'many' to enable invocation batching. Batched invocations are processed one at a time per listener.
maxBatchSize No Host default: 1 Maximum connector events per invocation, from 1 through 32. When omitted or set to 0, uses defaultMaxBatchSize from host.json. Without batching, the effective batch size must be 1.
maxConcurrentCalls No Host default: 16 Maximum concurrent single-event processing tasks per listener on one instance. When omitted or set to 0, uses defaultMaxConcurrentCalls from host.json. Must be non-negative. Doesn't apply to batched invocations.
targetPendingEventThreshold No Host default: 16 Target pending events per instance for target-based scaling. When omitted or set to 0, uses defaultTargetPendingEventThreshold from host.json. Must be non-negative. Doesn't change batch size or invocation concurrency; the runtime can override the scaling target.

For app-wide defaults, see Polling host.json settings. For handler input shapes, see Binding types.

Polling endpoint

The function's connection setting selects the prefix for the polling endpoint. For example, the prefix "ConnectorNamespace" uses ConnectorNamespace__pollingEndpoint. Define this setting under Values in local.settings.json for local development or in app settings for a deployed function app, as shown in the polling examples.

Retrieve the polling endpoint from the Connector Namespace portal, or derive it from the trigger configuration's service-generated pollingEndpoints.receiveUri as follows. Replace the placeholders with your resource values.

Requires Azure CLI, jq, and sed.

triggerConfigId="/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.Web/connectorGateways/<namespace-name>/triggerConfigs/<trigger-config-name>"
triggerConfig=$(az rest --method get \
    --url "${triggerConfigId}?api-version=2026-05-01-preview" \
    --query '{receiveUri:properties.pollingEndpoints.receiveUri,name:name}' \
    --output json)
receiveUri=$(printf '%s' "$triggerConfig" | jq -r '.receiveUri')
pollingEndpoint=$(printf '%s' "$receiveUri" |
    sed -E 's#/(api/)?trigger[Cc]onfigs/[^/]+/receive$##')
triggerConfigName=$(printf '%s' "$triggerConfig" | jq -r '.name')
printf '%s\n' "ConnectorNamespace__pollingEndpoint=$pollingEndpoint" \
    "OnNewEmailTriggerConfigName=$triggerConfigName"

Derive the setting from the service-generated Receive URI as follows:

Service pollingEndpoints.receiveUri <Connection>__pollingEndpoint
https://<connector-namespace-host>/api/triggerconfigs/<name>/receive https://<connector-namespace-host>
https://<host>/api/connectorGateways/<id>/triggerconfigs/<name>/receive https://<host>/api/connectorGateways/<id>

Preserve the service-provided host and gateway identifier; don't guess a hostname or configure the full Receive URL, an operation path, a standalone /api base, or a query string.

The extension uses this endpoint with the trigger configuration name to construct polling operation URLs. For the credentials and access policies needed to call these URLs, see Polling authentication.

Polling trigger configuration

The function's trigger configuration name identifies the configuration to receive events from.

Polling trigger configuration values

Configuration value Description
Connection The authorized managed connector connection, such as Office 365 Outlook or SharePoint Online. This is separate from the function's connection setting, which identifies an app-settings prefix.
Operation name The connector trigger operation, such as OnNewEmailV3 or GetOnNewFileItems.
Parameters Values required by the operation, such as an Outlook folder or a SharePoint site and document library.
Trigger configuration name The name of this polling trigger configuration, referenced by the function directly or through an app setting.
Delivery mode How events are delivered from services, through polling or webhook mode.

Create a polling trigger configuration

  1. If you don't already have a connector namespace, create a connector namespace.

  2. Go to the Connector Namespace portal, and then select your namespace.

  3. In the namespace menu, select Triggers, and then select Create.

  4. Find the managed connector you want to use, and then select the event that should trigger the function.

  5. On the trigger configuration page, create a connection or select an existing connection. Creating a connection requires a one-time authentication with the external service.

  6. Provide the inputs required by the event. For example, the Office 365 Outlook new-email event requires the folder to monitor for new messages.

  7. For Destination type, choose Azure Functions.

  8. For delivery mode, choose Polling.

  9. Review the configuration, and then select Create.

Polling authentication

For polling, grant a connection-level access policy to the function app's managed identity (deployed) or your developer identity (local). The Functions host uses this identity's Microsoft Entra credentials to receive and acknowledge events through the polling endpoint. The Connector Namespace's own connection access is handled automatically.

The caller's policy grants access to the managed connector connection, not to the namespace itself. Signing in or enabling a managed identity doesn't grant the caller this access automatically.

Unlike webhook delivery, polling doesn't require a public callback URL or a function app system key because the function app retrieves events from the namespace rather than receiving callbacks.

The authentication settings in the following subsections use the prefix ConnectorNamespace, matching the trigger examples. If your function uses a different connection-setting prefix, use that prefix instead.

Grant access policies

Use either method to grant the polling caller access to the connection. You need permission to manage access policies on the connection. Use the caller's principal (object) ID, not its application (client) ID.

  1. Go to the Connector Namespace portal, and then select your namespace.
  2. Open Connections, and select the managed connector connection used by your polling trigger configuration.
  3. Open the connection's Access Policies tab.
  4. Add an access policy for the caller identity. For local development, use your developer account's object ID. For a deployed function app, use the principal (object) ID of the managed identity your app uses.
  5. Verify that the caller has an access policy on the connection.

Local development

  1. Sign in with your developer identity, such as by running az login. This is the Microsoft Entra account the extension uses to authenticate polling requests locally.
  2. Grant an access policy on the managed connector connection for that identity. Signing in alone doesn't grant access to the connection.
  3. Define the connection settings under Values in local.settings.json. Omit ConnectorNamespace__credential to use developer credentials.

Deployed function app

  1. Enable a system-assigned managed identity on the function app, or assign a user-assigned managed identity to it.
  2. Grant an access policy on the managed connector connection for that identity.
  3. Configure the following authentication settings in the function app's app settings:
App setting Value
ConnectorNamespace__credential managedidentity
ConnectorNamespace__clientId The client ID of the user-assigned managed identity to use for polling. Set only when using a user-assigned identity.

Alternatively, set ConnectorNamespace__managedIdentityResourceId to the user-assigned identity's resource ID instead of setting ConnectorNamespace__clientId. For a system-assigned identity, omit both selectors.

Polling usage

The Functions host connects outbound to the Connector Namespace to poll for events and acknowledge successful invocations. The extension passes the events to your function; you don't write a polling loop.

Delivery is at least once. Failed invocations aren't acknowledged, and events can be redelivered after the service-managed lock expires. Make processing idempotent.

If you use ConnectorEvent<T>.MessageId for deduplication, scope it to the namespace and trigger configuration; don't assume that message IDs are unique across triggers.

Set DeliveryMode = ConnectorTriggerDeliveryMode.Poll on [ConnectorTrigger], and supply the Connection and TriggerConfigName properties. See the polling examples.

For attribute properties, supported values, and defaults, see Polling attribute properties.

Set delivery_mode=func.DeliveryMode.POLL on @app.connector_trigger, and supply connection and trigger_config_name. See the polling examples.

The host receives one event per invocation unless cardinality=func.Cardinality.MANY enables batching. For raw batches, use typing.List[str] or typing.List[bytes]; supported SDK annotations supply a list of models. For options, supported values, and defaults, see Polling decorators.

Set deliveryMode: 'Poll', and supply connection and triggerConfigName in the registration options. See the polling examples.

The host receives one event per invocation unless cardinality: 'many' enables batching. Named and generic helpers combine the payload items from all events into one context. Direct app.connectorTrigger handlers instead receive the outer event array. For options, supported values, and defaults, see Polling registration options.

Scaling and concurrency

Webhook delivery

In webhook mode, the Connector Namespace sends HTTP requests to the extension's callback endpoint. Connector triggers scale like HTTP triggers, according to the hosting plan's HTTP scaling behavior and limits. For details, see Event-driven scaling in Azure Functions.

Polling delivery

In polling mode, the Connector Trigger uses target-based scaling based on the estimated event backlog for the trigger configuration in the Connector Namespace. The scaling target is independent of per-instance processing concurrency and batch size. For the scaling equation, configuration settings, and tuning guidance, see Managed connectors target-based scaling.

Webhook mode

Registration

Use the generic connectorTrigger function for an operation that doesn't have a connector-specific registration:

import { InvocationContext } from '@azure/functions';
import {
    connectorTrigger,
    ConnectorTriggerContext,
} from '@azure/functions-extensions-connectors';

connectorTrigger('OnConnectorEvent', {
    handler: async (
        context: ConnectorTriggerContext,
        invocationContext: InvocationContext,
    ) => {
        invocationContext.log(JSON.stringify(context.rawPayload));
    },
});

The generic registration defaults the item type to unknown. Validate the payload before accessing operation-specific properties. Configure the connector, operation, operation parameters, destination function, and callback authentication in the trigger configuration in Azure Connector Namespace.

Registration

Use the generic connectorTrigger function for an operation that doesn't have a connector-specific registration:

const {
    connectorTrigger,
} = require('@azure/functions-extensions-connectors');

connectorTrigger('OnConnectorEvent', {
    handler: async (context, invocationContext) => {
        invocationContext.log(JSON.stringify(context.rawPayload));
    },
});

The generic registration normalizes the callback envelope but doesn't validate the operation-specific payload shape. Validate the payload before accessing operation-specific properties. Configure the connector, operation, operation parameters, destination function, and callback authentication in the trigger configuration in Azure Connector Namespace.

Decorators

Apply connector_trigger to the function that receives the event payload:

import azure.functions as func

app = func.FunctionApp()


@app.function_name(name="OnConnectorEvent")
@app.connector_trigger(arg_name="payload")
def on_connector_event(payload: str) -> None:
    # Process the raw JSON payload.
    pass

The arg_name value identifies the function parameter that receives the payload. Configure the connector, operation, operation parameters, destination function, and callback authentication in the trigger configuration in Azure Connector Namespace.

Attributes

Unlike polling, webhook delivery doesn't require additional properties on the [ConnectorTrigger] attribute because webhook is the default delivery mode. You can also set DeliveryMode = ConnectorTriggerDeliveryMode.Webhook explicitly. Polling-specific properties don't apply to webhook delivery.

Webhook trigger configuration

The trigger configuration's callback URL identifies the destination function.

Webhook trigger configuration values

Configuration value Description
Connection The authorized managed connector connection, such as Office 365 Outlook or SharePoint Online.
Operation name The connector trigger operation, such as OnNewEmailV3 or GetOnNewFileItems.
Parameters Values required by the operation, such as an Outlook folder or a SharePoint site and document library.
Callback URL The Connector extension webhook endpoint for the destination function. See Webhook authentication.
Function name The registered function name in your app code.
Authentication The authentication configuration used to call the function app.

The functionName query-string value in the callback URL must match the registered function name. Valid webhook function names contain 1 to 128 letters, numbers, underscores, or hyphens.

Create a webhook trigger configuration

Create a trigger configuration by using Azure CLI or the Connector Namespace portal.

Configure the trigger

A trigger configuration in Azure Connector Namespace associates an external service event with the destination function callback.

Trigger configuration values

Configuration value Description
Connection The authorized managed connector connection, such as Office 365 Outlook or SharePoint Online.
Operation name The connector trigger operation, such as OnNewEmailV3 or GetOnNewFileItems.
Parameters Values required by the operation, such as an Outlook folder or a SharePoint site and document library.
Callback URL The Connector extension webhook endpoint for the destination function. See Webhook authentication.
Function name The registered function name in your app code.
Authentication The authentication configuration used to call the function app.

The functionName query-string value in the trigger configuration's callback URL must match the registered function name. Valid function names contain 1 to 128 letters, numbers, underscores, or hyphens.

The operation name is defined by the managed connector. You choose the function name in your code, and the trigger configuration maps the operation to that function. The examples in this article use these mappings:

Connector event Operation name Function name
New Office 365 Outlook email OnNewEmailV3 OnNewEmail
New SharePoint Online file GetOnNewFileItems OnSharepointNewFile
New Microsoft Teams channel message OnNewChannelMessage OnNewChannelMessage
Selected connector event The operation selected in the trigger configuration OnConnectorEvent
Connector event Operation name Function name
New Office 365 Outlook email OnNewEmailV3 OnNewEmail
New SharePoint Online file GetOnNewFileItems OnSharepointNewFile
Selected connector event The operation selected in the trigger configuration OnConnectorEvent

Create a trigger configuration

Create a trigger configuration by using Azure CLI or the Connector Namespace portal.

Before the extension can receive an event, create these resources and configurations:

  1. A Connector Namespace.
  2. A managed connector connection authorized to access the external service.
  3. A trigger configuration that selects the connector event, operation parameters, and delivery mode.

For webhook delivery, the trigger configuration also includes the callback URL and callback authentication.

Trigger configurations are Connector Namespace resources that you can also deploy through ARM or Bicep.

The Azure CLI examples below use a deployed function app. Deploy the app with the extension and the destination function before you run them.

The following Bash example uses Azure CLI and jq to create an Office 365 Outlook new-email trigger. Replace the placeholder values for your resources and connection:

resourceGroup="<RESOURCE_GROUP>"
namespaceName="<CONNECTOR_NAMESPACE>"
functionAppName="<FUNCTION_APP>"
functionName="OnNewEmail"
triggerName="<TRIGGER_NAME>"
connectionName="<CONNECTION_NAME>"
connectorName="office365"
operationName="OnNewEmailV3"
subscriptionId=$(az account show --query id --output tsv)

connectorKey=$(az functionapp keys list \
    --resource-group "$resourceGroup" \
    --name "$functionAppName" \
    --query "systemKeys.connector_extension" \
    --output tsv)

callbackUrl="https://${functionAppName}.azurewebsites.net/runtime/webhooks/connector?functionName=${functionName}"

notificationFile=$(mktemp)
trap 'rm -f "$notificationFile"' EXIT

jq -n \
    --arg callbackUrl "$callbackUrl" \
    --arg connectorKey "$connectorKey" \
    '{
        callbackUrl: $callbackUrl,
        authentication: {
            type: "QueryString",
            name: "code",
            value: $connectorKey
        }
    }' > "$notificationFile"

az connector-namespace trigger create \
    --resource-group "$resourceGroup" \
    --namespace "$namespaceName" \
    --name "$triggerName" \
    --connection-details "{connectionName:${connectionName},connectorName:${connectorName}}" \
    --operation-name "$operationName" \
    --parameters "[{name:folderPath,value:'Inbox'}]" \
    --notification-details "@$notificationFile" \
    --description "${connectorName} ${operationName} -> ${functionName}" \
    --metadata "{destinationType:functionApp,functionAppName:${functionAppName},functionAppResourceGroup:${resourceGroup},functionAppSubscriptionId:${subscriptionId},functionName:${functionName},recurrenceFrequency:Minute,recurrenceInterval:'5'}"

rm -f "$notificationFile"
trap - EXIT

The --parameters value is specific to the connector operation. In this example, folderPath selects the Outlook folder to monitor. The callback URL doesn't contain the system key. The notificationDetails.authentication object adds the key as a query-string secret when Connector Namespace invokes the function.

Webhook authentication

The Connector Namespace sends events to the function app, rather than the function app polling the namespace. By default, the Functions host authenticates these callbacks by validating the Connector extension's system key, named connector_extension.

The Connector Namespace handles access to its managed connector connection automatically. Unlike polling, the function app's identity doesn't need a connection access policy solely to receive webhook callbacks; the system key authorizes those requests to the function app.

Webhook callback URL

Deployed app

Use the extension's callback endpoint, without a key in the URL:

https://<FUNCTION_APP_HOSTNAME>/runtime/webhooks/connector?functionName=<FUNCTION_NAME>

The functionName value must match the registered function name: the [Function] attribute in C#, the @app.function_name decorator in Python, or the trigger registration in Node.js.

For a deployed app using default authentication, use the Connector extension's connector_extension system key, not an individual function key. After deploying the function app with the extension, retrieve the system key:

az functionapp keys list \
    --resource-group <RESOURCE_GROUP> \
    --name <FUNCTION_APP_NAME> \
    --query "systemKeys.connector_extension" \
    --output tsv

In the trigger configuration, store the key in notificationDetails.authentication, separately from the callback URL:

{
  "notificationDetails": {
    "callbackUrl": "https://<FUNCTION_APP_HOSTNAME>/runtime/webhooks/connector?functionName=<FUNCTION_NAME>",
    "authentication": {
      "type": "QueryString",
      "name": "code",
      "value": "<CONNECTOR_EXTENSION_KEY>"
    }
  }
}

When delivering an event, the Connector Namespace adds the key as the code query-string parameter. Keeping the key separate from the saved callback URL lets the portal mask it as a secret. Don't include the key in the saved callback URL or commit it to source control.

Existing trigger configurations that include the key in the callback URL continue to work. When you edit and save an existing trigger configuration, the key moves to notificationDetails.authentication.

System keys can't be scoped per trigger and require coordinated rotation between the function app and Connector Namespace. For identity-based callbacks without a shared key, see Built-in authentication.

Local webhook development

Webhook callbacks must reach your running Functions host from the Connector Namespace. When you run locally:

  1. Start the function app with Azure Functions Core Tools, enabling authorization:

    func start --enableAuth
    

    Important

    Always use --enableAuth when exposing your app via a dev tunnel. Without it, your function endpoint is completely unauthenticated on the public internet.

  2. Use a Microsoft dev tunnel to forward a public HTTPS endpoint to the local Functions host port. Set the tunnel port visibility to Public so the Connector Namespace can reach it.

  3. Build the callback URL with the tunnel hostname and the registered function name, and use it in the webhook trigger configuration. For example, a tunnel forwarding port 7071 to the OnNewFile function uses a URL like:

    https://<tunnel-id>-7071.usw2.devtunnels.ms/runtime/webhooks/connector?functionName=OnNewFile
    

    For a local host that stores secrets in Azurite, retrieve its connector_extension system key by using these PowerShell commands. Set $connStr to the well-known Azurite connection string:

    $connStr = "<azurite-connection-string>"
    
    # Find the most recent host.json blob
    $blobs = az storage blob list --container-name azure-webjobs-secrets --connection-string $connStr -o json | ConvertFrom-Json
    $blobName = ($blobs | Where-Object { $_.name -match '(^|/)host\.json$' } | Sort-Object { $_.properties.lastModified } | Select-Object -Last 1).name
    
    # Download and parse
    az storage blob download --container-name azure-webjobs-secrets --name $blobName --connection-string $connStr --file host-keys.json --no-progress
    $keys = Get-Content host-keys.json | ConvertFrom-Json
    $connectorKey = ($keys.systemKeys | Where-Object { $_.name -eq "connector_extension" }).value
    Remove-Item -LiteralPath host-keys.json
    

    Store the local host's connector_extension system key separately in notificationDetails.authentication, using the QueryString authentication format shown above.

  4. Keep the host and tunnel running while testing. Update the trigger configuration if the tunnel hostname changes.

Built-in authentication

For webhook callbacks without shared keys, use App Service built-in authentication (also called Easy Auth) with a managed identity. This configuration is independent of the function's programming language.

The Connector Namespace uses its system-assigned or user-assigned managed identity to request a Microsoft Entra ID token for each callback. Built-in authentication validates the token and the caller's identity before the request reaches the Functions host. For an end-to-end implementation without client secrets, see the built-in authentication sample.

This section covers authentication from the namespace to the function app. The Connector Namespace handles access to its managed connector connection automatically. For authentication to upstream services, see Azure connectors overview.

Function app configuration

Important

This configuration requires authentication across the entire function app, not just /runtime/webhooks/connector, and restricts access to the namespace's callback identity. Existing HTTP functions that require function keys continue to require those keys in addition to app-level authentication. Before applying this configuration to an existing app, ensure that API clients and health probes can satisfy the app-level authentication and authorization policy and any function-level key requirements. Otherwise, requests can fail with HTTP 401 or 403. If the app must accept other callers, adapt the authorization policy instead of copying this allowlist unchanged. For policy options, see Configure Microsoft Entra authorization.

Configure built-in authentication through the function app's authsettingsV2 ARM resource or its equivalent in Bicep. The sample uses the following key settings:

Setting Purpose
platform.enabled: true Enables built-in authentication.
globalValidation.requireAuthentication: true Requires authentication before requests reach the Functions host.
globalValidation.unauthenticatedClientAction: Return401 Returns HTTP 401 for unauthenticated callbacks instead of redirecting to a sign-in page.
identityProviders.azureActiveDirectory.enabled: true Enables Microsoft Entra token validation.
registration.clientId The application (client) ID of the Microsoft Entra app registration that represents the function app.
registration.openIdIssuer The issuer URL for your tenant: https://login.microsoftonline.com/{tenantId}/v2.0.
validation.allowedAudiences The Entra app's client ID and identifier URI. Tokens must carry an allowed audience in the aud claim.
validation.defaultAuthorizationPolicy.allowedPrincipals.identities The object (principal) IDs allowed to call the function app. The sample allows only the namespace's callback managed identity. Adapt this policy if your app has other callers. A valid token with an oid claim not in the allowlist is denied with HTTP 403.

The registration and validation settings in this table are under identityProviders.azureActiveDirectory.

The sample also assigns a user-assigned managed identity to the function app and federates it to the Entra app registration. Built-in authentication uses this federated identity credential to obtain client assertions without storing a client secret. The sample sets the app setting OVERRIDE_USE_MI_FIC_ASSERTION_CLIENTID to the function app identity's client ID and sets registration.clientSecretSettingName to that setting's name.

The function app identity used for federation is separate from the namespace's callback identity. The namespace's identity is the caller allowed by allowedPrincipals.identities.

After built-in authentication is configured to validate callbacks, disable the redundant system-key check in host.json:

{
  "version": "2.0",
  "extensions": {
    "connector": {
      "system": {
        "webhookAuthorizationLevel": "Anonymous"
      }
    }
  }
}

Only use Anonymous when another authentication layer validates requests before they reach the Functions host. This setting doesn't enable token validation by itself.

Connector Namespace configuration

Enable a system-assigned managed identity on the Connector Namespace, or attach a user-assigned identity to it. In the trigger configuration's notificationDetails.authentication, set:

Property Value
type ManagedServiceIdentity
audience The Entra app registration's client ID, matching an audience accepted by the function app.
identity The resource ID of the attached user-assigned managed identity. Omit this property for a system-assigned identity.

The namespace uses that identity to obtain a token and sends it in the callback's Authorization: Bearer <token> header. The token's iss identifies the tenant, aud identifies the target app, and oid identifies the namespace's managed identity.

The namespace handles its own access to the managed connector connection automatically. This access is separate from callback authorization, which you configure through built-in authentication on the function app.

Authentication flow and validation

  1. The Connector Namespace obtains a token for the configured audience by using its callback managed identity.
  2. The namespace sends the token with the event to the extension's webhook endpoint.
  3. Built-in authentication validates the token's signature, expiration, issuer, and audience, and checks that its oid matches an allowed identity. Missing or invalid tokens receive HTTP 401; valid tokens from an identity not in the allowlist receive HTTP 403.
  4. Only authorized requests reach the Functions host. With the redundant system-key check disabled, the extension invokes the destination function and binds the event body to its parameter.

Your function doesn't need application code to perform these access checks.

Webhook usage

The Connector Namespace sends events to the extension's webhook endpoint, where the functionName query-string value selects the function. The extension binds the event body to your function parameter; you don't implement an HTTP handler.

The function name must match the name in your [Function] attribute. Callbacks can include x-ms-* headers that identify the trigger configuration, connection, event type, and correlation ID, but these headers aren't available to your function through the Connector Trigger.

Use [ConnectorTrigger] without polling properties. Webhook is the default when you omit DeliveryMode. See the webhook examples.

Your function can receive the event payload using any of the supported .NET binding types.

The extension accepts HTTP POST and PUT requests with the application/json content type. A nonempty request body must contain valid JSON. Requests are subject to the Functions host request-body limit and upstream service limits; the extension doesn't impose a separate payload-size cap.

To configure the host request-body limit, set the app-wide FUNCTIONS_REQUEST_BODY_SIZE_LIMIT app setting in bytes and restart the host. This isn't a host.json setting and doesn't change Poll linked-output downloads, which use extensions.connector.maxLinkedOutputSizeInBytes. Larger limits don't guarantee supported payload sizes; account for buffering, worker memory, and upstream limits.

Webhook usage

The generic helper receives a ConnectorTriggerContext<T>. Its payload property contains the normalized callback envelope, items contains the event items, and rawPayload preserves the parsed input before normalization. Connector-specific registrations provide named arrays, such as emails, records, or messages.

Each invocation handles one callback, which can contain multiple payload items. For an operation without a connector-specific registration, the TypeScript item type defaults to unknown. Validate the payload before you access operation-specific properties. For supported typed registrations, see the Node.js connector extension reference.

Webhook usage

The trigger can bind the request body to str, dict, or bytes. When azurefunctions-extensions-connectors registers a converter for the function's SDK annotation, the worker instead deserializes the request body into the supported operation-specific type.

Each invocation handles one callback. Supported SDK bindings supply its payload items as a list; use an annotation such as list[office365.GraphClientReceiveMessage]. For the supported operation-specific annotations, see the operation signature mapping.

The extension accepts HTTP POST and PUT requests with the application/json content type. A nonempty request body must contain valid JSON. Requests are subject to the Functions host request-body limit and upstream service limits.

Metadata

The Connector trigger currently doesn't expose callback headers or other request metadata as binding data. The extension defines an empty binding data contract, so the function receives only the JSON request body in a binding type supported by the selected language.