Merk
Tilgang til denne siden krever autorisasjon. Du kan prøve å logge på eller endre kataloger.
Tilgang til denne siden krever autorisasjon. Du kan prøve å endre kataloger.
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 supplyconnectionandtriggerConfigNamein 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:
- Install the Node.js packages and configure the extension bundle.
- Create or reuse a namespace and connection, and create a polling trigger configuration.
- Get the polling endpoint.
- Configure caller credentials, connection access, and local or deployed settings.
- Use a polling example below, matching its
connectionandtriggerConfigNamevalues 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 supplyconnectionandtrigger_config_nameon@app.connector_trigger. - Webhook: The Connector Namespace sends events to the extension's callback endpoint. Webhook is the default when you omit
delivery_modeon@app.connector_trigger.
For help choosing a mode, see Choose a delivery mode.
Get started
Follow the setup path for your delivery mode:
- Install the Python packages and configure the extension bundle.
- Create or reuse a namespace and connection, and create a polling trigger configuration.
- Get the polling endpoint.
- Configure caller credentials, connection access, and local or deployed settings.
- Use a polling example below, matching its
connectionandtrigger_config_namevalues 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
DeliveryModeon the[ConnectorTrigger]attribute.
For help choosing a mode, see Choose a delivery mode.
Get started
Follow the setup path for your delivery mode:
- Install the extension.
- Create or reuse a namespace and connection, and create a polling trigger configuration.
- Get the polling endpoint.
- Configure caller credentials, connection access, and local or deployed settings.
- Use an example below, matching its
ConnectionandTriggerConfigNamevalues 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 fromConnectorNamespace__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 theOnNewEmailTriggerConfigNamesetting. 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 fromConnectorNamespace__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 theOnNewFileTriggerConfigNamesetting. 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 fromConnectorNamespace__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 theOnNewTeamsMessageTriggerConfigNamesetting. 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.
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
If you don't already have a connector namespace, create a connector namespace.
Go to the Connector Namespace portal, and then select your namespace.
In the namespace menu, select Triggers, and then select Create.
Find the managed connector you want to use, and then select the event that should trigger the function.
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.
Provide the inputs required by the event. For example, the Office 365 Outlook new-email event requires the folder to monitor for new messages.
For Destination type, choose Azure Functions.
For delivery mode, choose Polling.
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.
- Go to the Connector Namespace portal, and then select your namespace.
- Open Connections, and select the managed connector connection used by your polling trigger configuration.
- Open the connection's Access Policies tab.
- 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.
- Verify that the caller has an access policy on the connection.
Local development
- 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. - Grant an access policy on the managed connector connection for that identity. Signing in alone doesn't grant access to the connection.
- Define the connection settings under
Valuesin local.settings.json. OmitConnectorNamespace__credentialto use developer credentials.
Deployed function app
- Enable a system-assigned managed identity on the function app, or assign a user-assigned managed identity to it.
- Grant an access policy on the managed connector connection for that identity.
- 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.
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:
- A Connector Namespace.
- A managed connector connection authorized to access the external service.
- 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:
Start the function app with Azure Functions Core Tools, enabling authorization:
func start --enableAuthImportant
Always use
--enableAuthwhen exposing your app via a dev tunnel. Without it, your function endpoint is completely unauthenticated on the public internet.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.
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
OnNewFilefunction uses a URL like:https://<tunnel-id>-7071.usw2.devtunnels.ms/runtime/webhooks/connector?functionName=OnNewFileFor a local host that stores secrets in Azurite, retrieve its
connector_extensionsystem key by using these PowerShell commands. Set$connStrto 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.jsonStore the local host's
connector_extensionsystem key separately innotificationDetails.authentication, using theQueryStringauthentication format shown above.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
- The Connector Namespace obtains a token for the configured audience by using its callback managed identity.
- The namespace sends the token with the event to the extension's webhook endpoint.
- Built-in authentication validates the token's signature, expiration, issuer, and audience, and checks that its
oidmatches an allowed identity. Missing or invalid tokens receive HTTP 401; valid tokens from an identity not in the allowlist receive HTTP 403. - 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.
Related authentication documentation
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.