NAV
shell python javascript

Introduction

Welcome to Notivize!

Notivize is a event-driven notification engine.

Based on events from your system, Notivize executes rules you configure to deliver your notifications to your users.

When you need to add, remove, or change a notification, or switch channels or cadences, you won't need to change, test, and deploy your code.

Show me

What Can I Do With Notivize?

Notivize can send emails, SMS, and mobile push notifications to your users.

Notivize will do this based on rules you have configured in the Notivize management portal, which describe how certain events should result in certain messages.

You can also easily change the template, swap channels, and add limits on how often a notification is sent.

Sending events is easy and secure. Notivize generates a code sample to show you how after you set up your first rule.

Show me

Does Notivize replace my email sending service?

You do not need to configure an email service to send emails with Notivize; however, if you already have a domain/reputation, you can use an existing Sendgrid account to deliver your email messages.

Does Notivize replace my SMS sending service?

You do not need to configure an SMS service to send SMS with Notivize; however, if you already have a number/identity, you can use an existing Twilio number to deliver your SMS messages.

Show me

Sending Events to Notivize

Notivize is powerful but you still need to help us help you! We watch a stream of data you send, called events, to help us decide when to execute your rules. Before you can send events, you need a unique event stream URL.

To get started, create a rule in the Notivize management portal. Your unique event stream URL will be provided in the code sample.

How do I send my events to Notivize?

After you create a rule, Notivize will generate a code sample showing you where to send your data and the minimum fields you should send based on the data used in your rule.

You are welcome and encouraged to send more data. Notivize will only use the fields referenced in your rules and templates, but you'll have access to the rest when you add or update rules and templates in the future.

Where should I integrate with Notivize?

To maximize the power of Notivize, you should send all changes to all fields of your data model. This allows you to have maximum flexibility in the Notivize rules you write today and in the future.

In a mobile application, this might be at the model persistence portion of a model-view-controller architecture.

In a single-page web app without a backend component, you would likely want to send whenever you write to local storage or whichever persistence mechanism you are using.

In a backend API or service, you might send the data in a post-commit database hook.

In More Detail

Event Stream Authentication

Notivize offers two ways to secure your event endpoints against unwanted event injection: API key authentication and JWT authentication. Read more about them and choose which is most appropriate for your use case.

API Key Authentication

API keys are a form of "shared secret" authentication, wherein a long string of random characters is generated by Notivize, and your code uses this same string when communicating with Notivize to prove your identity, since only Notivize and you should know the key. API keys are commonly used for server-to-server integrations where the code runs inside a controlled environment and the API key can be kept secret.

API keys should not embedded in front-end HTML/JavaScript, or in a mobile application such as and Android or iOS app. Any code which runs on the end user's computer (as opposed to your server) is inherently insecure against snooping.

API keys are standard practice for most server-side deployments, including APIs and services in C, C++, Go, Java (non-Android), Node.js, Python, Ruby, and more.

To add an API key: - Click "Settings" in the left menu - Click "Identity & Authentication" - Scroll to "API Keys" - Click "Request API Key" - Name your key - Copy the key for use in your code - Click "Done"

To configure API key authentication - Click "Workspaces" in the left menu - Select the workspace - Select the notification - Scroll to "Secure your endpoint" - Select your existing API key

Your code samples will update to show how to send the API key with your events.

import requests

# In your post-commit hook, for example
# Your data will probably be different!
MODEL_OBJECT = {
  'id':'123',
  'aqi': 88.5,
  'owner_email': 'foo@bar.com',
}

response = requests.post('https://events-api.notivize.com/<EVENT_PATH>', json=MODEL_OBJECT, headers={'Authorization': 'Bearer <API_KEY>'})

print(response)
# Your data will probably be different!
curl -v -X POST -H 'Authorization: Bearer <API_KEY>' --data '{"id": "123", "aqi": 88.5, "owner_email": "foo@bar.com"}' https://events-api.notivize.com/<EVENT_PATH>
// In your post-commit hook, for example
// Your data will probably be different!
const MODEL_OBJECT = {"id": "123", "aqi": 88.5, "owner_email": "foo@bar.com"}

let request = new XMLHttpRequest()
request.onreadystatechange = function() {
  if (this.readyState === 4) {
    console.log(this.status)
    console.log(this.responseText)
  }
}
request.open("POST", "https://events-api.notivize.com/<EVENT_PATH>", true)
request.setRequestHeader("Content-Type", "application/json")
request.setRequestHeader("Authorization", "Bearer <API_KEY>")
request.send(JSON.stringify(MODEL_OBJECT))

Show me

JWT Authentication

JWT authentication is a form of cryptographic authentication, wherein a trusted source who knows the identity of the user issues a "token" to the user which is cryptographically signed. This token is easy for anyone (e.g. Notivize) to verify, but can only be created by the trusted source (often a social network or an IaaS platform such as Auth0). JWTs are usually used for delegated sign-on on major web platforms such as "Sign in with Google".

JWTs are appropriate for many client-side web frameworks such as AngularJS, React, or Vue, or any mobile or even server-side application which uses authentication that already produces a JWT for the user.

To add a JWT provider: - Click "Settings" in the left menu - Click "Identity & Authentication" - Scroll to "JWT Providers" - Click "Add JWT Provider" - Enter the URL to your public JWK set. These are the public keys which anybody can use to verify the authenticity of a JWT issued by this provider. This parameter is required, and will ensure that only JWTs issued by this provider are honored. - Optionally, enter an audience parameter to verify. This is not required, but is recommended if you are directly using a major social login provider such as Google OpenID. This will ensure that only JWTs which are issued by this provider for this audience are honored. - Click "Check API Credentials"

To configure JWT authentication - Click "Workspaces" in the left menu - Select the workspace - Select the notification - Scroll to "Secure your endpoint" - Select your existing JWT provider

Your code samples will update to show how to send the JWT with your events.

import requests

# In your post-commit hook, for example
# Your data will probably be different!
MODEL_OBJECT = {
  'id':'123',
  'aqi': 88.5,
  'owner_email': 'foo@bar.com',
}

response = requests.post('https://events-api.notivize.com/<EVENT_PATH>', json=MODEL_OBJECT, headers={'Authorization': 'Bearer <JWT>'})

print(response)
# Your data will probably be different!
curl -v -X POST -H 'Authorization: Bearer <JWT>' --data '{"id": "123", "aqi": 88.5, "owner_email": "foo@bar.com"}' https://events-api.notivize.com/<EVENT_PATH>
// In your post-commit hook, for example
// Your data will probably be different!
const MODEL_OBJECT = {"id": "123", "aqi": 88.5, "owner_email": "foo@bar.com"}

let request = new XMLHttpRequest()
request.onreadystatechange = function() {
  if (this.readyState === 4) {
    console.log(this.status)
    console.log(this.responseText)
  }
}
request.open("POST", "https://events-api.notivize.com/<EVENT_PATH>", true)
request.setRequestHeader("Content-Type", "application/json")
request.setRequestHeader("Authorization", "Bearer <JWT>")
request.send(JSON.stringify(MODEL_OBJECT))

Show me