When should I choose batch loading?

Choose batch loading when you want predictable load windows, lower always-on activity, or tighter control over when `COPY INTO` runs. This blueprint provisions a Snowflake task that runs once an hour so the path is still end to end. Tune `taskIntervalMinutes` if you want a tighter or looser cadence.

Can I keep the raw payloads in cloud storage?

Yes. Every path writes the raw payloads to cloud storage before Snowflake loads them (S3 on AWS, Blob Storage on Azure, Cloud Storage on GCP). See the variant page you picked for specifics on how the loading path reads from or retains those objects.

Load custom webhook events into Snowflake on AWS with Firehose direct delivery

This guide shows how to land custom webhook events in Snowflake on AWS with Firehose direct delivery.

It covers the storage, eventing, and Snowflake objects for this setup so you can get raw events flowing first and shape downstream tables later.

On AWS, this guide uses AWS Lambda for the public handler and Amazon S3 for staging or backup storage. From there the loading path for this variant (Firehose direct delivery) carries records into Snowflake.

The Firehose direct delivery path validates the webhook at the edge and forwards the raw JSON straight into Amazon Data Firehose, which then delivers into Snowflake with second-level latency. This path also needs a Snowflake service user plus a base64-encoded private key because Firehose authenticates to Snowflake separately from the Pulumi provider. This blueprint provisions the public Lambda URL, the Firehose delivery stream, the direct Snowflake destination, and an S3 backup bucket that keeps every record Firehose forwards.

This guide leaves sender registration in your hands, but the stack still creates the public endpoint and shared secret. Your sender posts JSON and signs the raw body with HMAC SHA256 in the X-Webhook-Signature header.

Quickstart

Download the blueprint zip for your language below, or create a new Pulumi project with the same file layout shown in the Download section.
Install dependencies for your selected language and configure Snowflake plus AWS.
Deploy the stack to create the public Lambda URL, the Firehose delivery stream, the S3 backup bucket, and the Snowflake loading objects.
Register your sender with the exported endpoint and shared secret, then send a test event.
Query the landing table in Snowflake to confirm the event arrived.

After the first test event, new rows usually appear in seconds.

Prerequisites

a Pulumi account and the Pulumi CLI
an AWS account where you can create the Lambda, S3, IAM, and loading-path resources this variant provisions
a Snowflake account where you can create databases, schemas, and loading roles
a sender you control that can compute HMAC SHA256 for the raw body and POST JSON to the exported endpoint
no extra Pulumi config is required. Your sender uses the exported webhookUrl and webhookSecret.

For the Pulumi language you selected:

Python 3.11 or newer and a virtual environment tool

Node.js 20 or newer and npm

Initialize your stack for AWS with:

pulumi stack init dev
pulumi config set aws:region us-west-2

Set up credentials with Pulumi ESC

This guide needs cloud credentials, Snowflake credentials, and any source-specific token required to provision the webhook. A single ESC environment is usually the smallest setup that still keeps secrets out of local files.

values:
  aws:
    login:
      fn::open::aws-login:
        oidc:
          roleArn: arn:aws:iam::123456789012:role/pulumi-esc-oidc
          sessionName: webhook-snowflake
  snowflake:
    login:
      fn::open::snowflake-login:
        oidc:
          account: <your-snowflake-account>
          user: ESC_SERVICE_USER
    organizationName: <your-org-name>
    accountName: <your-account-name>

  environmentVariables:
    SNOWFLAKE_USER: ${snowflake.login.user}
    SNOWFLAKE_TOKEN: ${snowflake.login.token}
  pulumiConfig:
    snowflake:organizationName: ${snowflake.organizationName}
    snowflake:accountName: ${snowflake.accountName}
    snowflake:authenticator: OAUTH
    snowflake:role: PULUMI_DEPLOYER

    webhook-to-snowflake:firehoseUser: ${snowflake.login.user}
    webhook-to-snowflake:firehosePrivateKeyBase64:
      fn::secret: <base64-encoded-snowflake-private-key>

Then reference it from your stack config:

environment:
  - <your-org>/<your-environment>
config:
  webhook-to-snowflake:database: LANDING_ZONE_WEBHOOKS

What you get in the download

The downloadable example zip includes:

Pulumi.yaml
the Pulumi program, dependency files, cloud runtime support files, and reusable components for the language you pick below
a README with a shorter quick start for this exact setup

__main__.py as the Pulumi entrypoint
components/webhook_ingestion.py for the public webhook endpoint
components/direct_snowflake_ingestion.py for the Snowflake loading path
lambda/webhook_handler.py for request validation and writes into the selected ingestion path
requirements.txt for the root Pulumi project

index.ts as the Pulumi entrypoint
components/webhook_ingestion.ts for the public webhook endpoint
components/direct_snowflake_ingestion.ts for the Snowflake loading path
lambda/webhook_handler.py for request validation and writes into the selected ingestion path
package.json and tsconfig.json for the root Pulumi project

The next sections show the same entrypoint and component files that ship in the download.

Blueprint Pulumi program

This blueprint shows the full resource wiring for the AWS Firehose direct delivery path with a Custom sender source. The downloadable repo uses the same entrypoint and component files shown below.

import pulumi
import pulumi_aws as aws
import pulumi_random as random
import pulumi_snowflake as snowflake


from components.direct_snowflake_ingestion import DirectSnowflakeIngestion
from components.webhook_ingestion import WebhookIngestion

config = pulumi.Config()
database_name = config.get("database") or "LANDING_ZONE_WEBHOOKS"
firehose_user = config.require("firehoseUser")
firehose_private_key_base64 = config.require_secret("firehosePrivateKeyBase64")


bucket = aws.s3.Bucket("backup-bucket")
database = snowflake.Database("landing-db", name=database_name)
schema = snowflake.Schema("raw-schema", name="RAW", database=database.name)

snowflake_config = pulumi.Config("snowflake")
snowflake_account_url = (
    f"https://{snowflake_config.require('organizationName')}"
    f"-{snowflake_config.require('accountName')}.snowflakecomputing.com"
)

webhook_secret = random.RandomPassword("webhook-secret", length=32, special=False)

pipeline = DirectSnowflakeIngestion(
    "source-events",
    bucket_arn=bucket.arn,
    bucket_name=bucket.bucket,
    database=database.name,
    schema_name=schema.name,
    snowflake_account_url=snowflake_account_url,
    snowflake_user=firehose_user,
    snowflake_private_key_base64=firehose_private_key_base64,
)

ingestion = WebhookIngestion(
    "source-webhooks",
    bucket_name=bucket.bucket,
    bucket_arn=bucket.arn,
    webhook_secret=webhook_secret.result,
    firehose_stream_name=pipeline.stream_name,
    firehose_stream_arn=pipeline.stream_arn,
)

endpoint_url = ingestion.function_url

pulumi.export("webhookUrl", endpoint_url)
pulumi.export("webhookSecret", webhook_secret.result)

pulumi.export("backup_bucket_name", bucket.bucket)
pulumi.export("delivery_stream_name", pipeline.stream_name)
pulumi.export("table_name", pipeline.table_name)

import * as aws from "@pulumi/aws";
import * as pulumi from "@pulumi/pulumi";
import * as random from "@pulumi/random";
import * as snowflake from "@pulumi/snowflake";


import { DirectSnowflakeIngestion } from "./components/direct_snowflake_ingestion";
import { WebhookIngestion } from "./components/webhook_ingestion";

const config = new pulumi.Config();
const databaseName = config.get("database") ?? "LANDING_ZONE_WEBHOOKS";
const firehoseUser = config.require("firehoseUser");
const firehosePrivateKeyBase64 = config.requireSecret("firehosePrivateKeyBase64");


const bucket = new aws.s3.Bucket("backup-bucket");
const database = new snowflake.Database("landing-db", { name: databaseName });
const schema = new snowflake.Schema("raw-schema", {
    name: "RAW",
    database: database.name,
});

const snowflakeConfig = new pulumi.Config("snowflake");
const snowflakeAccountUrl = `https://${snowflakeConfig.require("organizationName")}-${snowflakeConfig.require("accountName")}.snowflakecomputing.com`;

const sharedSecret = new random.RandomPassword("webhook-secret", {
    length: 32,
    special: false,
});

const pipeline = new DirectSnowflakeIngestion("source-events", {
    bucketArn: bucket.arn,
    bucketName: bucket.bucket,
    database: database.name,
    schemaName: schema.name,
    snowflakeAccountUrl,
    snowflakeUser: firehoseUser,
    snowflakePrivateKeyBase64: firehosePrivateKeyBase64,
});

const ingestion = new WebhookIngestion("source-webhooks", {
    bucketName: bucket.bucket,
    bucketArn: bucket.arn,
    webhookSecret: sharedSecret.result,
    firehoseStreamName: pipeline.streamName,
    firehoseStreamArn: pipeline.streamArn,
});

const endpointUrl = ingestion.functionUrl;

export const webhookUrl = endpointUrl;
export const webhookSecret = sharedSecret.result;

export const backupBucketName = bucket.bucket;
export const deliveryStreamName = pipeline.streamName;
export const tableName = pipeline.tableName;

Reusable components

The entrypoint stays small because the real ingestion work lives in reusable modules. These are the same component files packaged in the downloadable blueprint for this setup.

components/webhook_ingestion.py

Accepts the public webhook request, validates the signature, normalizes the payload, and writes the raw event into the landing path for this setup.

from __future__ import annotations

from dataclasses import dataclass

import pulumi
import pulumi_aws as aws


@dataclass
class WebhookIngestion:
    function_url: pulumi.Output[str]
    function_name: pulumi.Output[str]

    def __init__(
        self,
        name: str,
        *,
        bucket_name: pulumi.Input[str],
        bucket_arn: pulumi.Input[str],
        webhook_secret: pulumi.Input[str],
        firehose_stream_name: pulumi.Input[str] | None = None,
        firehose_stream_arn: pulumi.Input[str] | None = None,
    ) -> None:
        policy_statements = [
            aws.iam.GetPolicyDocumentStatementArgs(
                effect="Allow",
                actions=[
                    "logs:CreateLogGroup",
                    "logs:CreateLogStream",
                    "logs:PutLogEvents",
                ],
                resources=["arn:aws:logs:*:*:*"],
            ),
            aws.iam.GetPolicyDocumentStatementArgs(
                effect="Allow",
                actions=["s3:PutObject"],
                resources=[pulumi.Output.from_input(bucket_arn).apply(lambda arn: f"{arn}/incoming/*")],
            ),
        ]
        if firehose_stream_arn is not None:
            policy_statements.append(
                aws.iam.GetPolicyDocumentStatementArgs(
                    effect="Allow",
                    actions=["firehose:PutRecord", "firehose:PutRecordBatch"],
                    resources=[firehose_stream_arn],
                )
            )

        assume_role_policy = aws.iam.get_policy_document_output(
            statements=[
                aws.iam.GetPolicyDocumentStatementArgs(
                    effect="Allow",
                    principals=[
                        aws.iam.GetPolicyDocumentStatementPrincipalArgs(
                            type="Service",
                            identifiers=["lambda.amazonaws.com"],
                        )
                    ],
                    actions=["sts:AssumeRole"],
                )
            ]
        )

        role = aws.iam.Role(
            f"{name}-role",
            assume_role_policy=assume_role_policy.json,
        )

        policy = aws.iam.get_policy_document_output(
            statements=policy_statements
        )

        environment_variables = {
            "LANDING_BUCKET": bucket_name,
            "LANDING_PREFIX": "incoming",
            "WEBHOOK_SECRET": webhook_secret,
        }
        if firehose_stream_name is not None:
            environment_variables["FIREHOSE_STREAM_NAME"] = firehose_stream_name

        aws.iam.RolePolicy(
            f"{name}-policy",
            role=role.id,
            policy=policy.json,
        )

        function = aws.lambda_.Function(
            f"{name}-function",
            runtime="python3.11",
            role=role.arn,
            handler="webhook_handler.handler",
            timeout=30,
            memory_size=256,
            code=pulumi.AssetArchive(
                {"webhook_handler.py": pulumi.FileAsset("lambda/webhook_handler.py")}
            ),
            environment=aws.lambda_.FunctionEnvironmentArgs(
                variables=environment_variables
            ),
        )

        function_url = aws.lambda_.FunctionUrl(
            f"{name}-url",
            authorization_type="NONE",
            function_name=function.name,
            cors=aws.lambda_.FunctionUrlCorsArgs(
                allow_methods=["POST"],
                allow_origins=["*"],
            ),
        )

        self.function_url = function_url.function_url
        self.function_name = function.name

components/direct_snowflake_ingestion.py

Creates the Snowflake-side loading resources for this setup: the landing stage, the destination table, and the Firehose direct delivery loading path.

from __future__ import annotations

from dataclasses import dataclass

import pulumi
import pulumi_aws as aws
import pulumi_snowflake as snowflake


@dataclass
class DirectSnowflakeIngestion:
    stream_name: pulumi.Output[str]
    stream_arn: pulumi.Output[str]
    table_name: pulumi.Output[str]

    def __init__(
        self,
        name: str,
        *,
        bucket_arn: pulumi.Input[str],
        bucket_name: pulumi.Input[str],
        database: pulumi.Input[str],
        schema_name: pulumi.Input[str],
        snowflake_account_url: pulumi.Input[str],
        snowflake_user: pulumi.Input[str],
        snowflake_private_key_base64: pulumi.Input[str],
    ) -> None:
        assume_role_policy = aws.iam.get_policy_document_output(
            statements=[
                aws.iam.GetPolicyDocumentStatementArgs(
                    effect="Allow",
                    principals=[
                        aws.iam.GetPolicyDocumentStatementPrincipalArgs(
                            type="Service",
                            identifiers=["firehose.amazonaws.com"],
                        )
                    ],
                    actions=["sts:AssumeRole"],
                )
            ]
        )

        role = aws.iam.Role(
            f"{name}-role",
            assume_role_policy=assume_role_policy.json,
        )

        policy = aws.iam.get_policy_document_output(
            statements=[
                aws.iam.GetPolicyDocumentStatementArgs(
                    effect="Allow",
                    actions=[
                        "s3:AbortMultipartUpload",
                        "s3:GetBucketLocation",
                        "s3:GetObject",
                        "s3:ListBucket",
                        "s3:ListBucketMultipartUploads",
                        "s3:PutObject",
                    ],
                    resources=[bucket_arn, pulumi.Output.from_input(bucket_arn).apply(lambda arn: f"{arn}/*")],
                )
            ]
        )

        aws.iam.RolePolicy(
            f"{name}-policy",
            role=role.id,
            policy=policy.json,
        )

        table = snowflake.Table(
            f"{name}-table",
            database=database,
            schema=schema_name,
            name="WEBHOOK_EVENTS_DIRECT",
            columns=[
                snowflake.TableColumnArgs(name="CONTENT", type="VARIANT"),
                snowflake.TableColumnArgs(name="METADATA", type="VARIANT"),
            ],
        )

        stream = aws.kinesis.FirehoseDeliveryStream(
            f"{name}-stream",
            destination="snowflake",
            snowflake_configuration={
                "account_url": snowflake_account_url,
                "database": database,
                "schema": schema_name,
                "table": table.name,
                "user": snowflake_user,
                "private_key": snowflake_private_key_base64,
                "role_arn": role.arn,
                "content_column_name": "CONTENT",
                "metadata_column_name": "METADATA",
                "data_loading_option": "VARIANT_CONTENT_AND_METADATA_MAPPING",
                "s3_backup_mode": "AllData",
                "s3_configuration": {
                    "role_arn": role.arn,
                    "bucket_arn": bucket_arn,
                    "buffering_interval": 60,
                    "buffering_size": 5,
                    "compression_format": "GZIP",
                },
            },
        )

        self.stream_name = stream.name
        self.stream_arn = stream.arn
        self.table_name = table.name

components/webhook_ingestion.ts

Accepts the public webhook request, validates the signature, normalizes the payload, and writes the raw event into the landing path for this setup.

import * as aws from "@pulumi/aws";
import * as pulumi from "@pulumi/pulumi";

export interface WebhookIngestionArgs {
    bucketName: pulumi.Input<string>;
    bucketArn: pulumi.Input<string>;
    webhookSecret: pulumi.Input<string>;
    firehoseStreamName?: pulumi.Input<string>;
    firehoseStreamArn?: pulumi.Input<string>;
}

export class WebhookIngestion {
    public readonly functionUrl: pulumi.Output<string>;
    public readonly functionName: pulumi.Output<string>;

    constructor(name: string, args: WebhookIngestionArgs) {
        const assumeRole = aws.iam.getPolicyDocumentOutput({
            statements: [
                {
                    effect: "Allow",
                    principals: [
                        {
                            type: "Service",
                            identifiers: ["lambda.amazonaws.com"],
                        },
                    ],
                    actions: ["sts:AssumeRole"],
                },
            ],
        });

        const role = new aws.iam.Role(`${name}-role`, {
            assumeRolePolicy: assumeRole.json,
        });

        const statements: aws.types.input.iam.GetPolicyDocumentStatementArgs[] = [
            {
                effect: "Allow",
                actions: [
                    "logs:CreateLogGroup",
                    "logs:CreateLogStream",
                    "logs:PutLogEvents",
                ],
                resources: ["arn:aws:logs:*:*:*"],
            },
            {
                effect: "Allow",
                actions: ["s3:PutObject"],
                resources: [pulumi.interpolate`${args.bucketArn}/incoming/*`],
            },
        ];
        if (args.firehoseStreamArn) {
            statements.push({
                effect: "Allow",
                actions: ["firehose:PutRecord", "firehose:PutRecordBatch"],
                resources: [args.firehoseStreamArn],
            });
        }

        const policy = aws.iam.getPolicyDocumentOutput({
            statements,
        });

        const environmentVariables: Record<string, pulumi.Input<string>> = {
            LANDING_BUCKET: args.bucketName,
            LANDING_PREFIX: "incoming",
            WEBHOOK_SECRET: args.webhookSecret,
        };
        if (args.firehoseStreamName) {
            environmentVariables.FIREHOSE_STREAM_NAME = args.firehoseStreamName;
        }

        new aws.iam.RolePolicy(`${name}-policy`, {
            role: role.id,
            policy: policy.json,
        });

        const fn = new aws.lambda.Function(`${name}-function`, {
            runtime: "python3.11",
            role: role.arn,
            handler: "webhook_handler.handler",
            timeout: 30,
            memorySize: 256,
            code: new pulumi.asset.AssetArchive({
                "webhook_handler.py": new pulumi.asset.FileAsset("lambda/webhook_handler.py"),
            }),
            environment: {
                variables: environmentVariables,
            },
        });

        const url = new aws.lambda.FunctionUrl(`${name}-url`, {
            authorizationType: "NONE",
            functionName: fn.name,
            cors: {
                allowMethods: ["POST"],
                allowOrigins: ["*"],
            },
        });

        this.functionUrl = url.functionUrl;
        this.functionName = fn.name;
    }
}

components/direct_snowflake_ingestion.ts

Creates the Snowflake-side loading resources for this setup: the landing stage, the destination table, and the Firehose direct delivery loading path.

import * as aws from "@pulumi/aws";
import * as pulumi from "@pulumi/pulumi";
import * as snowflake from "@pulumi/snowflake";

export interface DirectSnowflakeIngestionArgs {
    bucketArn: pulumi.Input<string>;
    bucketName: pulumi.Input<string>;
    database: pulumi.Input<string>;
    schemaName: pulumi.Input<string>;
    snowflakeAccountUrl: pulumi.Input<string>;
    snowflakeUser: pulumi.Input<string>;
    snowflakePrivateKeyBase64: pulumi.Input<string>;
}

export class DirectSnowflakeIngestion {
    public readonly streamName: pulumi.Output<string>;
    public readonly streamArn: pulumi.Output<string>;
    public readonly tableName: pulumi.Output<string>;

    constructor(name: string, args: DirectSnowflakeIngestionArgs) {
        const assumeRole = aws.iam.getPolicyDocumentOutput({
            statements: [
                {
                    effect: "Allow",
                    principals: [
                        {
                            type: "Service",
                            identifiers: ["firehose.amazonaws.com"],
                        },
                    ],
                    actions: ["sts:AssumeRole"],
                },
            ],
        });

        const role = new aws.iam.Role(`${name}-role`, {
            assumeRolePolicy: assumeRole.json,
        });

        const policy = aws.iam.getPolicyDocumentOutput({
            statements: [
                {
                    effect: "Allow",
                    actions: [
                        "s3:AbortMultipartUpload",
                        "s3:GetBucketLocation",
                        "s3:GetObject",
                        "s3:ListBucket",
                        "s3:ListBucketMultipartUploads",
                        "s3:PutObject",
                    ],
                    resources: [args.bucketArn, pulumi.interpolate`${args.bucketArn}/*`],
                },
            ],
        });

        new aws.iam.RolePolicy(`${name}-policy`, {
            role: role.id,
            policy: policy.json,
        });

        const table = new snowflake.Table(`${name}-table`, {
            database: args.database,
            schema: args.schemaName,
            name: "WEBHOOK_EVENTS_DIRECT",
            columns: [
                { name: "CONTENT", type: "VARIANT" },
                { name: "METADATA", type: "VARIANT" },
            ],
        });

        const stream = new aws.kinesis.FirehoseDeliveryStream(`${name}-stream`, {
            destination: "snowflake",
            snowflakeConfiguration: {
                accountUrl: args.snowflakeAccountUrl,
                database: args.database,
                schema: args.schemaName,
                table: table.name,
                user: args.snowflakeUser,
                privateKey: args.snowflakePrivateKeyBase64,
                roleArn: role.arn,
                contentColumnName: "CONTENT",
                metadataColumnName: "METADATA",
                dataLoadingOption: "VARIANT_CONTENT_AND_METADATA_MAPPING",
                s3BackupMode: "AllData",
                s3Configuration: {
                    roleArn: role.arn,
                    bucketArn: args.bucketArn,
                    bufferingInterval: 60,
                    bufferingSize: 5,
                    compressionFormat: "GZIP",
                },
            },
        });

        this.streamName = stream.name;
        this.streamArn = stream.arn;
        this.tableName = table.name;
    }
}

Verify the data landed

After you send a test event, query Snowflake to confirm the records are visible:

SELECT CONTENT,
       METADATA:IngestionTime::TIMESTAMP AS ingested_at
FROM LANDING_ZONE_WEBHOOKS.RAW.WEBHOOK_EVENTS_DIRECT
ORDER BY ingested_at DESC;

For this path, Firehose streams directly into Snowflake and also keeps every forwarded record in the S3 backup bucket.

Operating notes

Keep the first table as a raw landing zone. Flatten and model into downstream tables later.
Rotate the shared webhook secret when you roll senders or suspect exposure.
Watch the landing storage path and Snowflake task history so failed loads and malformed payloads do not go unnoticed.
Use a least-privilege Snowflake reader role for analysts instead of querying with the loading role.
When you choose batch loading, tune taskIntervalMinutes to match how quickly you want new files copied into Snowflake and how much warehouse activity you want between loads.