Receive notifications with Pub/Sub

You’re already on Google Cloud, and standing up a public HTTPS endpoint just to receive Nylas webhooks means more infrastructure to secure and scale. If your consumers already read from Pub/Sub, it’s cleaner to drop events straight onto a topic.

Nylas can deliver notifications to a Google Cloud Pub/Sub topic as an alternative to an HTTP webhook. You subscribe to the same triggers, but events land in your topic instead of hitting a URL you host. The Pub/Sub delivery diagram shows the path from Nylas to your subscribers.

How Nylas delivers to a Pub/Sub channel

Your Google Cloud project

Create a topic

Add a subscription your app reads from.

Your Google Cloud project

Let Nylas publish

Give the Nylas service account roles/pubsub.publisher on the topic.

Your app

Create the channel

In the Dashboard (Notifications, then Create Pub/Sub Channel) or with POST /v3/channels/pubsub. Set the topic name and trigger types.

Topic name in the wrong format

Channel not created

Nylas returns 400.

Nylas

Save the channel

Nylas checks the topic format only. It doesn't publish a test message.

When subscribed data changes

Nylas

Publish to your topic

JSON payload with a trigger_type attribute. No ordering key is set.

Optional parameters

• compressed_delivery: gzip-compresses the payload and adds a content_encoding: gzip attribute. Without it, the payload is plain JSON.

Publishing keeps failing

Channel marked failing

Then failed if errors continue. Set it back to active after you fix it.

Your subscriber

Pull or receive messages

Read from your subscription. Messages can arrive out of order.

Nylas publishes notifications to a Google Cloud topic you own. IAM on the topic controls who can publish and read, so there's no challenge or signature to handle.

Diagram as text

• Your Google Cloud project: Create a topic: Add a subscription your app reads from.
• Your Google Cloud project: Let Nylas publish: Give the Nylas service account roles/pubsub.publisher on the topic.
• Your app: Create the channel: In the Dashboard (Notifications, then Create Pub/Sub Channel) or with POST /v3/channels/pubsub. Set the topic name and trigger types.
  • Topic name in the wrong format → Channel not created: Nylas returns 400.
• Nylas: Save the channel: Nylas checks the topic format only. It doesn't publish a test message.
• Nylas: Publish to your topic: JSON payload with a trigger_type attribute. No ordering key is set. (When subscribed data changes)
  • Optional parameter compressed_delivery: gzip-compresses the payload and adds a content_encoding: gzip attribute. Without it, the payload is plain JSON.
  • Publishing keeps failing → Channel marked failing: Then failed if errors continue. Set it back to active after you fix it.
• Your subscriber: Pull or receive messages: Read from your subscription. Messages can arrive out of order.

How do I send notifications to a Pub/Sub topic?

Create a Pub/Sub channel with a POST /v3/channels/pubsub request. You pass the fully-qualified topic (in the form projects/<id>/topics/<id>), a list of trigger_types, and optional notification_email_addresses for downtime alerts. Nylas then publishes 1 message to that topic per matching event, across any of the 43 trigger types, and your Pub/Sub subscribers consume them.

The request below creates a Pub/Sub channel subscribed to one trigger.

Request

curl --request POST \
  --url 'https://api.us.nylas.com/v3/channels/pubsub' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --data-raw '{
    "description": "PubSub Test",
    "trigger_types": ["message.send_success"],
    "encryption_key": "",
    "topic": "projects/<YOUR_PROJECT_ID>/topics/<YOUR_TOPIC_ID>",
    "notification_email_addresses": ["[email protected]"]
  }'

Create a Pub/Sub channel from the terminal

For high-volume delivery, a Pub/Sub channel queues notifications to a Google Cloud topic instead of pushing them to an HTTPS endpoint. The Nylas CLI sets one up: nylas webhook pubsub create registers a topic and the triggers you want, with no public HTTPS receiver to host or keep online.

nylas webhook pubsub create --topic projects/my-project/topics/nylas-events --triggers message.created,event.created

Pub/Sub suits pull-based, high-throughput pipelines where you’d rather consume a queue than run a public receiver. The command requires 2 flags, the --topic path and the --triggers list, and the same trigger types you’d use for webhooks apply. See the webhook pubsub create command reference.

When should I use Pub/Sub instead of webhooks?

Pub/Sub fits when you’re on Google Cloud and want a managed queue between Nylas and your code, so you don’t run or expose a public webhook endpoint. The queue absorbs spikes and gives you retries and fan-out for free, which matters when a grant recovers after being invalid and the API replays up to 72 hours of missed events. Both channels carry the same notification payloads.

Reach for a standard HTTPS webhook instead when you aren’t on Google Cloud or want the simplest possible setup, since a webhook needs only 1 reachable URL.

Things to know about Pub/Sub channels

A few details carry over from webhooks. The channel subscribes to the same trigger_types as an HTTP webhook, so each event becomes 1 message on the topic with an identical payload; only the delivery mechanism changes. The topic must be the fully-qualified Google Cloud name, and you grant Nylas publish rights to it during setup.

You can also set compressed_delivery to gzip-compress payloads before they’re published to the topic. For the channel reference and Pub/Sub permissions, see Pub/Sub notification channels.

What’s next

• Pub/Sub notification channels for the full setup and Google Cloud permissions
• Get real-time updates with webhooks for the HTTPS webhook alternative
• Webhook notification schemas for every trigger’s payload
• Handle grant expiry and re-authentication for the backfill bursts Pub/Sub absorbs