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.

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 GCP 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 GCP 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