Send a welcome message from Firebase Auth

Firebase Auth has no webhook. It runs your code instead, as a Cloud Function on the user-created event.

What you will build

Prerequisites

A Firebase project with Authentication enabled, and the Firebase CLI
A published to send

Use the non-blocking trigger

Firebase gives you two ways to run code when a user is created, and for a welcome message the older one is the right one. functions.auth.user().onCreate() is a 1st-gen trigger. It runs after the user exists, asynchronously, and nothing you do in it can affect the signup. There is no 2nd-gen equivalent, and Firebase says so plainly: 2nd gen does not support Authentication triggers. The two generations coexist in one file, so this is not a reason to avoid 2nd gen elsewhere. beforeUserCreated is the 2nd-gen blocking function, and it is the wrong tool here for three reasons:

It requires upgrading the project to Firebase Authentication with Identity Platform.
It must respond within 7 seconds, after which Firebase returns an error and the client operation fails. A slow send would block a signup.
Deleting the function without unregistering its trigger prevents all users from authenticating.

Blocking is for deciding whether someone may sign up. Sending a welcome is not that, and a notification outage should never stop a registration.

Set it up

Install the dependencies

In your functions directory:

npm install firebase-functions firebase-admin @trycourier/courier

Store your Courier key as a secret

Firebase keeps secrets in Cloud Secret Manager and injects them at runtime.

firebase functions:secrets:set COURIER_API_KEY

Bind it to the function that needs it. Secret values are hidden until the function runs, so they cannot be read at deploy time.

Write the function

The handler receives a UserRecord. Its uid, email, and displayName are the three fields worth reading here.

functions/index.js

const functions = require("firebase-functions/v1");
const Courier = require("@trycourier/courier");

exports.sendWelcome = functions
  .runWith({ secrets: ["COURIER_API_KEY"] })
  .auth.user()
  .onCreate(async (user) => {
    const { uid, email, displayName } = user;

    if (!email) return; // phone-only and anonymous signups have none

    const courier = new Courier({ apiKey: process.env.COURIER_API_KEY });

    // Firebase's uid becomes the Courier user id, so both systems agree.
    await courier.profiles.create(uid, {
      profile: { email, name: displayName },
    });

    await courier.send.message({
      message: {
        to: { user_id: uid },
        template: "nt_01kx4h2jdafq8bk9aftxak4b40",
        data: { name: displayName ?? "there" },
      },
    });
  });

The runWith call is what grants access to the secret, which then arrives on process.env. Importing from firebase-functions/v1 explicitly keeps this working alongside 2nd-gen functions in the same file.

Anonymous and phone-only signups have no email, and the trigger fires for both. Returning early is what stops a crash on the first anonymous session.

Deploy

firebase deploy --only functions:sendWelcome

Verify

Create a user

Read the function log

firebase functions:log --only sendWelcome

The trigger is asynchronous, so a failure appears here and nowhere else. It will not surface to the user.

Confirm the send

Open in Courier and confirm the message.

What the trigger covers

More than Auth0’s equivalent, which is worth knowing if you are comparing the two.

Sign-up route	Fires
Email and password	Yes
A federated provider, including Google, on first sign-in	Yes
Anonymous session	Yes, with no `email`
Created through the Admin SDK	Yes
A custom token	No

The custom-token gap is the one to plan around. If you mint your own tokens for an existing identity system, this trigger never runs, and the profile write belongs wherever you create that user instead.

Get started

Send your first message

Build a notification

Send to many people

Send when something happens

Let users choose

Go live

Move to Courier

Send a welcome message from Firebase Auth

What you will build

Prerequisites

Use the non-blocking trigger

Set it up

Verify

What the trigger covers

​What you will build

​Prerequisites

​Use the non-blocking trigger

​Set it up

​Verify

​What the trigger covers

What you will build

Prerequisites

Use the non-blocking trigger

Set it up

Verify

What the trigger covers