Using Webhooks In Passport To Delete User Data

John Philips

Using webhooks in Passport

If your inbox looks anything like mine, it’s currently full of messages from companies updating their privacy policies and terms of service. This is mainly due to a newly adopted EU regulation, the General Data Protection Regulation or GDPR, which goes into effect on May 25, 2018. The GDPR grants a set of “digital rights” to EU citizens, including a “right to erasure.” Basically, this means a user can request that their data be deleted, and there can be substantial fines if a company is not able to honor these requests.

In this post, we’ll show how to set up webhooks in Passport to delete all of a user’s data when they delete their account. In Passport, webhooks are used to subscribe or listen to events in the system, so we’ll create a webhook that listens to the user.delete event.

What is a Webhook?

In case you are not familiar with webhooks in Passport and other platforms, they are an effective component of interactive user experiences on websites and applications. In the most basic terms, webhooks are simple event notifications that send a message to the application that something happened. Upon receiving that message, the application can react. It may trigger a change in the user’s interface, or it can initiate more complex processes within the application. The options are endless and developers are taking advantage of this technique to make more engaging experiences. For more information, there’s a useful introduction to webhooks here.

Creating Webhooks in Passport

There are two ways to create webhooks in Passport. The first is to use the Passport Backend UI and it is pretty straight-forward. After logging in, click on Settings → Webhook. This tutorial video shows exactly how the interface works.

Using Webhooks In Passport

The second way to create webhooks in Passport is programmatically by using the API and sending a JSON request. Simply send a POST request to /api/webhook. This will create the ID for the webhook automatically. If you want to specify the ID, post to /api/webhook/{webhookId}.

The fully qualified URL depends on where you are running the Passport Backend. If it is running on your machine, the URL would be http://localhost:9011/api/webhook. If Inversoft is hosting Passport, the URL will be shown in your Inversoft Account.

Authentication

The webhook API requires authentication. To access it, you’ll need make the request using an API key sent in an Authorization header. Using curl, the request would look something like this:

(Learn more about creating an API key or how authentication works in Passport.)

JSON Request Example

There are three required parameters:

  • The parameter connectTimeout sets the time in milliseconds that Passport will wait when connecting to the webhook.
  • The parameter readTimeout sets the time in milliseconds that Passport will wait when reading data from the webhook.
  • The url provides the address Passport will connect to when the webhook is called.

In addition to the required parameters, you’ll want to add:

  • One or more applicationIds: These specify the applications associated with the webhook. If you’d rather configure the webhook to work for all your applications, set the global flag to true and omit the application IDs. However, if no IDs are specified and global flag is false, the webhook will never get called.
  • The events that trigger the webhook: In this case, we want to be passed the user.delete event. (The full list of events can be found here.)
  • Any credentials needed to access the server hosting the webhook: The example shows a user name and password, which would be used if the server has HTTP basic authentication enabled. You can also include an SSL Certificate in PEM format, if your server requires an SSL connection.
  • An Authorization header that contains an API key: This prevents malicious access to the webhook. Without the key, the webhook cannot be executed. In the example, our hook is deleting data so it makes sense to be cautious.

(The full list of webhook parameters is documented here.)

API Response

If the webhook was set up properly, you’ll get a back a response code of ‘200’ and a JSON body that looks similar to the request.

If the request was malformed or invalid, you’ll get back a ‘400’ response code and a JSON object detailing the errors. A ‘401’ response indicates an authorization problem. Either the authorization header was omitted or the API key was invalid.

Event JSON Example

Once you have the webhook configured, Passport will post JSON data to the URL when a matching event occurs. Our webhook is subscribed to the user.delete event. When this occurs, Passport will post a JSON request to the webhook URL. The JSON will look something like this:

An Example Webhook

For our example, we’re going write our webhook using Express, a simple web framework for Node.js.

This sets up a route to handle the URL for our webhook. The first bit of code checks that the Authorization header contains the correct API key. (This key would be stored in the Express app.)

The line savedItems.deleteAll(request.event.user.id) is a call to delete the user’s data. Once the data has been deleted, our webhook will respond with a status code of 200. With the webhook attached, Passport will wait to delete the user until it gets a success code back from the webhook. By deleting the user’s saved data in response to the user.delete event we are in effect keeping our application database in sync with the Passport user database.

Wrapping Up

This post shows the power and simplicity of using webhooks in Passport. By subscribing to events, your application can easily respond to changes in user data. This publish and subscribe pattern is a core feature of Passport’s architecture. If you have any questions or problems, send us a message and we’ll be happy to help.

Learn More About Passport

Passport is designed to be the most flexible and secure Customer Identity and Access Management (CIAM) solution available on the market. More than a login tool, we provide registration, data search, user segmentation and advanced user management across applications. Find out more about Passport and sign up for a free trial today.

Try Passport

Comments are closed.