Webhooks

In this guide, we will look at how to register and consume webhooks to integrate your app with DevRIFT. With webhooks, your app can know when something happens in DevRIFT, such as a person's Security Key being authorised or a Magic Link being accepted.

Registering webhooks

To register a new webhook, you need to have a URL in your app that DevRIFT can send a POST request to. You can configure a new webhook from the DevRIFT dashboard under Webhooks. Give your webhook a name, pick the events you want to listen for, and add the URL DevRIFT should send the request to.

Now, whenever something of interest happens in your app, a webhook is fired off by DevRIFT. In the next section, we'll look at how to consume webhooks.

Consuming webhooks

When your app receives a webhook request from DevRIFT, check the type attribute to see what event caused it. The first part of the event type will tell you the payload type, e.g., a magic link, backup codes, etc.

Example webhook payload

{
  "id": "b051VBR7gmoRil2x",
  "type": "magic.created",
  "payload": {
    "id": "XAz4eIcvWR40rogK"
    // ...
  }
}

In the example above, that a Magic Link was created, and the payload type is magic.

See all event types

Event types

  • Name
    magic.created
    Type
    Description

    A magic link was created and sent to a user.

  • Name
    magic.verified
    Type
    Description

    A magic link was successfully verified.

  • Name
    magic.deleted
    Type
    Description

    A magic link was deleted, this can either occur when it expires, if you chose to delete it manually, or if we suspect it was compromised.

    A reason attribute is included in the payload to indicate why the magic link was deleted.

  • Name
    mfa.created
    Type
    Description

    An MFA code was created and sent to a user.

  • Name
    mfa.verified
    Type
    Description

    An MFA code was successfully verified for a user.

  • Name
    mfa.deleted
    Type
    Description

    An MFA code was deleted, this can either occur when it expires, if another code was sent to the same user, or if we suspect it was compromised.

    A reason attribute is included in the payload to indicate why the MFA code was deleted.

  • Name
    activation.created
    Type
    Description

    An Account Activation link was created and sent to a user.

  • Name
    activation.verified
    Type
    Description

    An account activation link was successfully verified.

  • Name
    activation.deleted
    Type
    Description

    An account activation link was deleted, this can either occur when it expires, if you chose to delete it manually, or if we suspect it was compromised.

    A reason attribute is included in the payload to indicate why the activation link was deleted.

  • Name
    hsm.session.created
    Type
    Description

    Occurs whenever a HSM Session is created

  • Name
    hsm.session.requires_input
    Type
    Description

    Occurs whenever a HSM Session transitions to require user input

  • Name
    hsm.session.destoryed
    Type
    Description

    An existing HSM Session was destoryed, this is likely to happen due to a user's browser being closed, session expiring, or if we have recieved a Security Key input.

  • Name
    hsm.created
    Type
    Description

    A Security Key was added to a user's account.

  • Name
    hsm.verified
    Type
    Description

    A user successfully authenticated using their Security Key.

  • Name
    hsm.deleted
    Type
    Description

    A Security Key was deleted from a user's account. This can either occur when you submit a request to delete it, or in the rare case that we suspect it was compromised.

    A reason attribute is included in the payload to indicate why the Security Key was deleted.

  • Name
    sudo.created
    Type
    Description

    A Sudo Session was created for a user.

  • Name
    sudo.requires_input
    Type
    Description

    Occurs whenever a Sudo Session transitions to require user input

  • Name
    sudo.updated
    Type
    Description

    An existing Sudo Session was updated, this is likely to happen due to a user's browser being closed and reopened.

  • Name
    sudo.deleted
    Type
    Description

    A Sudo Session was deleted, this can either occur when it expires, if you chose to delete it manually, or if we suspect it was compromised.

    A reason attribute is included in the payload to indicate why the Sudo Session was deleted.

  • Name
    identity.verification_session.created
    Type
    Description

    Occurs whenever a VerificationSession is created

  • Name
    identity.verification_session.canceled
    Type
    Description

    Occurs whenever a VerificationSession is canceled

  • Name
    identity.verification_session.processing
    Type
    Description

    Occurs whenever a VerificationSession transitions to processing

  • Name
    identity.verification_session.redacted
    Type
    Description

    Occurs whenever a VerificationSession is redacted.

  • Name
    identity.verification_session.requires_input
    Type
    Description

    Occurs whenever a VerificationSession transitions to require user input

  • Name
    identity.verification_session.verified
    Type
    Description

    Occurs whenever a VerificationSession transitions to verified

  • Name
    mitm.created
    Type
    Description

    Occurs whenever an MITM Session is created.

  • Name
    mitm.detected
    Type
    Description

    Occurs whenever an MITM Attack is detected.

  • Name
    halt.triggered
    Type
    Description

    Occurs whenever the HALT system is triggered for your Application.

  • Name
    halt.resolved
    Type
    Description

    Occurs whenever a HALT is resolved for your Application.

  • Name
    halt.updated
    Type
    Description

    Occurs whenever the settings for the HALT system are updated for your Application.

    If you do not recognise this activity, please contact support immediately.

Example payload

{
  "id": "d026X7c3NmzRjh70",
  "type": "magic.created",
  "payload": {
    "id": "SIuAFUNKdSYHZF2w",
    "magic_id": "x2dFXg4VctGw7Avx",
    "end-user": {
      "id": "aXc4ejbYdRx09xuD",
      "user_email": "[email protected]"
    },
    "devrift": {
      "sent_from": "[email protected]",
      "custom_fields": {
        "custom_domain": null,
        "custom_logo": null
      },
    },
    "created_at": 1673011882,
    "expires_at": 1673019098,
  }
}

Security

To know for sure that a webhook was, in fact, sent by DevRIFT instead of a malicious actor, you can verify the request signature. Each webhook request contains a header named DevRIFT-Signature, and you can verify this signature by using your secret webhook key. The signature is an HMAC SHA256 hash of the request payload hashed using your secret key. Here is an example of how to verify the signature in your app:

Verifying a request

// This verifies the signature manually. You can do this manually, but it is easier to use the SDK.
$payload = @file_get_contents('php://input');
$sig_header = $_SERVER['HTTP_DEVRIFT_SIGNATURE'];

$hash = hash_hmac('sha256', $payload, "whsec_...");

if (hash_equals($hash, $signature)) {
  // Request is verified
} else {
  // Request could not be verified
}

DevRIFT requires the raw body of the request to perform signature verification. If you’re using a framework, make sure it doesn’t manipulate the raw body. Any manipulation to the raw body of the request causes the verification to fail.

If your generated signature matches the DevRIFT-Signature header, you can be sure that the request was truly coming from DevRIFT. It's essential to keep your secret webhook key safe — otherwise, you can no longer be sure that a given webhook was sent by DevRIFT. Don't commit your secret webhook key to GitHub!

Reason Attribute

The reason attribute is used inside of Webhooks. Currently, the only times you will see a reason attribute is when the type of webhook is deleted for any type of payload.

It is used to provide a reason for why the payload was deleted. See the docs for more information.