Pub/Sub hooks

You can create and use Pub/Sub hooks with ReachFive. This page introduces Pub/Sub hooks and instructs you on how to create one using the ReachFive Console.

Pub/Sub is an asynchronous messaging service that offers real-time message delivery along with reliable memory storage of the messages. Pub/Sub also decouples event production from event processing.

We will briefly look at the publisher-subscriber (Pub/Sub) relationship below.

If you don’t immmediately recognise the terms here, check out the important terms below.
pub sub
  1. The publisher app connects to a topic in the Pub/Sub service. It then sends messages to this topic.

  2. Messages are retained in message storage.

  3. Messages are forwarded from the topic to all associated subscriptions individually.

  4. The messages are transmitted by pushing to an endpoint or pulling from the service itself.

  5. The subscriber application informs the Pub/Sub service that messages are received.

Why use Pub/Sub?

A major advantage of using Pub/Sub (as opposed to webhooks) is message storage (step 2 above) as well as subscriber acknowledgement of receiving the message (step 5 above). Until all subscriber applications have acknowledged receiving the message, Pub/Sub continues distributing the message to all relevant subscribers. This greatly improves guaranteed message delivery.

Create Pub/Sub hook from console

The Pub/Sub hook that you create in the ReachFive Console is triggered after an event is generated similar to that of a typical Post-event webhook.

Prerequisites

  • You must have access to the ReachFive Console.

  • You must have a Developer, Manager, or Administrator role.

  • You must have the Pub/Sub Hooks feature enabled.

Instructions

  1. Log in to your ReachFive Console.

  2. Go to Settings  Pub/Sub Hooks  User Events.

  3. Select New Pub/Sub hook or edit edit icon an existing Pub/Sub Hook.

  4. Enable your Pub/Sub hook.

  5. Give your hook a Key. This is a unique reference for the hook.

  6. From the drop-down menu, choose the Event types that will trigger the Pub/Sub hook.

    Event types

    Name Description

    login

    Emitted after a successful authentication.

    logout

    Emitted after a user logs out.

    signup

    Emitted after a successful signup.

    managed_user_created

    Emitted after a new user is successfully created through the Management API.

    unlink

    Emitted after a successful unlink identity.

    email_updated

    Emitted after a successful email update.

    phone_number_updated

    Emitted after a successful phone number update.

    password_reset_requested

    Emitted after a successful password reset request.

    password_changed

    Emitted after a successful password change.

    password_reset

    Emitted after a successful password reset process.

    profile_compromised

    Emitted when the IFP module detects a compromised profile.

    otp_sent

    Emitted after a one-time password (otp) is successfully sent (via sms or email) for verification.

    This includes otps for Two-factor authentication (2FA) flows.

    login_not_matching_password

    Emitted after an unsuccessful login attempt due to the password not matching.

    login_matching_password

    Emitted after a successful login via the /password/login call.

    user_updated

    Emitted after a successful user update.

    user_deleted

    Emitted after a successful user deletion.

    We retain the user_deleted event type for a certain period of time after a user profile is deleted.

    user_updated_by_merge

    Emitted after a successful merge (for the updated user).

    user_deleted_by_merge

    Emitted after a successful merge (for the deleted user).

    email_verified

    Emitted after a successful email verification.

    phone_number_verified

    Emitted after a successful mobile number verification.

    user_created

    Emitted after successfully creating a new Lite profile.

    authorization_refused

    Emitted after an unsuccessful authorization attempt.

    authorization_deleted

    Emitted after authorization was deleted.

    authorization_granted

    Emitted after authorization was successfully granted.

    lite_merged_into_managed

    Emitted after a lite profile was succesfully merged into a managed profile.

    login_2nd_step

    Emitted after the user has successfully logged in using the Two-factor authentication (2FA) flow.

    ACCOUNT PROTECTION

    user_suspended

    Emitted after a successful user account suspension.

    user_unsuspended

    Emitted after a successful user account unsuspension.

    login_successful_suspended_account

    Emitted after an unsuccessful login attempt on a suspended account with the correct credentials.

    login_unverified_identifier

    Emitted when a user attempts to log in with an unverified identifier.

    This event is only emitted if the Block unverified login attempts feature is enabled.

    signup_compromised

    Emitted when a user profile is created with a suspicious IP.

    risky_login_notification

    Emitted when a risky login notification was sent to the user.

    risk_threshold_exceeded

    Emitted when the risk_score threshold was exceeded.

    WEBHOOK FAILURES

    pre_event_failure

    Emitted when a failure occurred in a pre-event webhook.

    Currently, you can only set up PubSub hooks to trigger based on this event. It’s not possible on standard pre/post event webhooks.

    post_event_failure

    Emitted when a failure occurred in a post-event webhook.

    Currently, you can only set up PubSub hooks to trigger based on this event. It’s not possible on standard pre/post event webhooks.

    pub_sub_event_failure

    Emitted when a failure occurred in a Pub/sub hook.

    RETRY FAILURE EVENTS

    email_failure

    Emitted if there is an error while sending an email. Occurs after the provider responds with an error after the 3rd attempt.

    sms_failure

    Emitted if there is an error while sending an sms. Occurs after the provider responds with an error after the 3rd attempt.

    USER LOCKOUT EVENTS

    profile_lockout

    Emitted each time a user profile is locked.

    MFA EVENTS

    mfa_phone_number_deleted

    Emitted after an MFA credential (phone number) is deleted.

    mfa_email_deleted

    Emitted after an MFA credential (email) is deleted.

    mfa_email_start_registration

    Emitted after an email is used to start the MFA registration process.

    mfa_email_verify_registration

    Emitted after an email has been verified as an MFA credential.

    mfa_phone_number_start_registration

    Emitted after a phone number is used to start the MFA registration process.

    mfa_phone_number_verify_registration

    Emitted after a phone number has been verified as an MFA credential.

    mfa_trusted_device_added

    Emitted after a device has been added as a trusted device .

    mfa_trusted_device_deleted

    Emitted after a device has been removed as a trusted device .

    CONSENT EVENTS

    consent.granted

    Emitted after a consent was successfully granted.

    consent.waiting

    Emitted after a DOI consent was moved to the waiting status. This means the consent is awaiting follow-up action from the user.

    consent.denied

    Emitted after a consent was officially rejected (denied).

    PASSKEY EVENTS

    webauthn_credential_created

    Emitted after a passkey was successfully created.

    webauthn_credential_deleted

    Emitted after a passkey was successfully deleted.

    GUEST EVENTS

    login_invalid_identifier_format

    Emitted after an unsuccessful login due to the identifier format.

    login_unknown_identifier

    Emitted after an unsuccessful login attempt due to an unknown identifier.

    signup_invalid_email_format

    Emitted after an unsuccessful signup attempt due to an invalid email format.

    signup_not_compliant_password

    Emitted after an unsuccessful signup attempt because the password was not compliant.

  7. Optionally, add Filters to your hook.

    Adding filters means only those fields matching the filter criteria are returned from the Pub/Sub hook.

    Filterable fields

    • user email

    • user email verified

    • user verified emails

    • user unverified emails

    • user phone number

    • user phone number verified

    • user username

    • user first name

    • user last name

    • user name

    • user nickname

    • user gender

    • user age

    • user external id

    • user authentication types

    • user providers

    • user devices

    • user city

    • user country

    • user nb of logins

    • user nb of friends

    • user nb of local friends

    • user first login

    • user last login

    • user last login type

    • user created at

    • user updated at

    • user lite only

    • user suspension status

    • user title

    • user locality

    • user region

    • user country

    • user recipient

    • user company

    • user address_complement

    • user custom fields

    • user consents

    • user Kakao Age range

    • user Kakao Connecting Information

  8. Choose the event fields and/or user fields you want to send in the request to your application. This is a comma-separated list.

    User fields should be prefixed with user.: emailuser.email.
  9. Enter your Project ID for your Google Cloud account.

  10. Enter the Topic where you want requests sent.

  11. Enter the Credentials (in JSON format) needed to connect to Google Cloud.

    Where do I get the credentials? 🤔

    External instructions

    These instructions are current as of July 5th, 2024. Refer to Google Cloud’s official documentation for the most up-to-date information.

    To get your credentials in JSON format from Google Cloud:

    1. Go to your Google Cloud console (GCP).

    2. Select your desired GCP project.

    3. Go to the API & Services section.

      1. Inside of API & Services, go to Credentials.

      2. Inside of API & Services, go to your Service accounts.

      3. Choose your desired Service Account (or create a new one if necessary).

      4. Go to Keys inside your chosen Service account. This is typically a tab at the top of the page.

      5. Add a new key.

        1. Select the key type, choose JSON.

        2. Click Create.

          This downloads the `.json `file which contains your service account credentials. You can only get your JSON file when first creating the key. If you forget it or have misplaced it, you’ll need to create a new key.

    4. Save this JSON file securely. You will need it for authentication in your application.

  12. Don’t forget to Save your input.

View Pub/Sub results

To view the User Events, you should go to your Pub/Sub page in your Google Cloud Platform (GCP) account.

  1. Go to Topics.

  2. Choose the desired Topic ID.

  3. Click View Messages.

  4. Select the desired Cloud Pub/Sub subscription.

  5. Follow the on-screen instructions.

Pub/sub hook failures

Sometimes, the Pub/sub hook may fail. In the event that the hook fails, we provide a user event type that allows you to look into why the hook failed.

For more details, see User Events.

Pub/sub hook
{
  "date": "2024-01-07T09:54:34.183123Z",
  "id": "AWUTz0..6KwGSiAAIMN",
  "type": "pub_sub_event_failure",
  "canal": "hook",
  "failed_hook_project": "webhook_host_unreachable",
  "failed_hook_message_key": "NOT_FOUND",
  "failed_hook_key": "failing_event",
  "failed_hook_user_event_type": "login_matching_password",
  "failed_hook_message": "…​ NOT_FOUND: Resource not found (resource=blah1234).",
  "failed_hook_topic": "blah1234"
}
Field Description

date

The date on which the event occurred.

id

User event id.

type

User event type.

canal

The channel through which the event was triggered.

failed_hook_key

The unique webhook key.

failed_hook_user_event_type

The user event for which the webhook was triggered.

failed_hook_topic

The topic ID of the pub/sub hook that failed.

failed_hook_message_key

The error message key. For example, NOT_FOUND.

failed_hook_message

The error message for the failed hook. This describes why it failed. For example, the topic ID may have not been found for pub/sub hooks or there is a duplicated external ID.

example
...
    "failed_hook_message": "{\"detail\": \"Duplicated external id\", \"code\": \"711\"}"
...

failed_hook_project

The project name of the pub/sub hook that failed.

Important terms

Topic

A named resource to which messages are sent by publishers.

Subscription

A named resource representing the stream of messages from a single, specific topic, to be delivered to the subscribing application.

Message

The combination of data and (optional) attributes that a publisher sends to a topic and is eventually delivered to subscribers.

Message attribute

A key-value pair that a publisher can define for a message.