App Hooks

App hooks are outbound connections to your app and your customers. There are two types of App hooks: webhooks (HTTP POSTs) and outbound emails.

Email hooks

Email hooks can only be configured for user.* event types. Email hooks are silently skipped for users who do not have an email address.

Webhooks

Outbound webhooks carry the same payload as responses from the Get an Event API call.

Fields

FieldValueReq/DefaultNotes
id id Auto-generated

App hook ID. Always starts with “hk_”. Example: hk_USwTRKQljEFpHF8ac6dbE

state active,
inactive
active
hook_type webhook,
email
webhook
event_type array Required Events that will trigger this hook.
realm_id realm_id null (all realms) Limit events to resources within this Realm ID.
delay integer 0 Delay of initial notification attempt; in seconds.
request hash

Hash of request attributes to add to Event. See notes.

webhook only:

destination url Required Target URL for HTTP POST.

email only:

email_from email noreply@loginrocket.com "From" address for email.
email_from_name email "From" name for email.
email_renderer html,
html+text,
markdown,
text
markdown

How email_template is interpreted. See below.

email_subject string Required "Subject" for email.
email_template string Required Body of email. See below.
email_to email If present, override "To" to this address. Useful for testing.
user_type all,
human,
api
all

Which user_type‘s should receive emails.

Event types

For email hooks, event_type must be an array of exactly one event type. Only user. types are supported.

For webhooks, event_type is an array of zero or more event types. An empty array is equivalent to all events, including any new event types added in the future.

Valid event types:

app_hook.created app_hook.deleted app_hook.updated auth_provider.created auth_provider.deleted auth_provider.updated login_policy.created login_policy.deleted login_policy.updated membership.created membership.deleted membership.updated org.created org.deleted org.updated realm.created realm.deleted realm.updated user.created user.deleted user.email.verification_requested user.email.verified user.login.failed user.login.initiated user.login.succeeded user.password_token.consumed user.password_token.created user.password_token.failed user.updated

Email renderers

email_renderer determines how email_template is used to create the email.

  • htmlemail_template treated as complete HTML body. No text version included.

  • html+text – Same as html, except a text version will also be automated created from the HTML version.

  • markdown (Recommended) – email_template treated as Markdown and rendered into both HTML and text. HTML version will sport a basic, clean HTML theme.

  • textemail_template treated as text. No HTML version included.

Email templates

Available variables for substitution:
{{email}} {{event_at}} {{first_name}} {{full_name}} {{ip}} {{realm_name}} {{token}} {{url}} {{username}}

Variable substitution works for all email_renderer types.

Permissions

MethodPermissions
List, Get read
Create, Update, Delete admin_realm

List app hooks

List all app hooks.

Parameters

ParamValueDefault
hook_type hook_type Filter by hook_type
realm_id realm_id Filter by Realm ID. Null is a valid value.
state state Filter by state
after hook_id ID of the last app hook you've seen
max_results integer 100 Range: 1-1000
sort id id
direction asc,
desc
asc

Request

Example
GET /v1/app_hooks
AuthRocket::AppHook.all


AuthRocket::AppHook.all realm_id: 'rl_0v1zTHXhtNgmDaXaDYSAqx'

Response

Example

Status: 200

{ "more_results" : false,
  "collection" : [
    { "id" : "hk_0v1zXKOfq1qKaFg2bLASQl",
      "realm_id" : "rl_0v1zTHXhtNgmDaXaDYSAqx",
      "state" : "active",
      "event_type" : ["user.login.failed"],
      "hook_type" : "webhook",
      "object" : "app_hook",
      "destination" : "https://example.com/webhooks/authrocket"
    }
  ]
}
[#<AuthRocket::AppHook:0x3fc21aa16dfc>
  id: "hk_0v1zXKOfq1qKaFg2bLASQl",
  attribs: {
    "realm_id"=>"rl_0v1zTHXhtNgmDaXaDYSAqx",
    "state"=>"active",
    "event_type"=>["user.login.failed"],
    "hook_type"=>"webhook",
    "object"=>"app_hook",
    "destination"=>"https://example.com/webhooks/authrocket"
  },
  metadata: {
    "more_results"=>false
  }
]

Get an app hook

Retrieve a specific app hook.

Request

Example
GET /v1/app_hooks/:hook_id
AuthRocket::AppHook.find 'hk_0v1zXKOfq1qKaFg2bLASQl'

Response

Example

Status: 200

{ "id" : "hk_0v1zXKOfq1qKaFg2bLASQl",
  "realm_id" : "rl_0v1zTHXhtNgmDaXaDYSAqx",
  "state" : "active",
  "event_type" : ["user.login.failed"],
  "hook_type" : "webhook",
  "object" : "app_hook",
  "destination" : "https://example.com/webhooks/authrocket"
}
#<AuthRocket::AppHook:0x3fc21aa16dfc>
  id: "hk_0v1zXKOfq1qKaFg2bLASQl",
  attribs: {
    "realm_id"=>"rl_0v1zTHXhtNgmDaXaDYSAqx",
    "state"=>"active",
    "event_type"=>["user.login.failed"],
    "hook_type"=>"webhook",
    "object"=>"app_hook",
    "destination"=>"https://example.com/webhooks/authrocket"
  }

Create an app hook

Create a new app hook.

Request

Example
POST /v1/app_hooks
{ "app_hook" :
  { "realm_id" : "rl_0v1zTHXhtNgmDaXaDYSAqx",
    "event_type" : ["user.login.failed"],
    "destination" : "https://example.com/webhooks/authrocket"
  }
}
hook = AuthRocket::AppHook.create(
  realm_id: "rl_0v1zTHXhtNgmDaXaDYSAqx",
  event_type: ["user.login.failed"],
  destination: "https://example.com/webhooks/authrocket"
)

Response

Example

Status: 201, with same body as Get an App Hook.

On success, returns same object as Get an App Hook.

On failure, returns an object without an id, but with errors:

# => #<AuthRocket::AppHook:0x3fde5fa18df8> id: nil, ...
hook.errors?
# => true
hook.valid?
# => false
hook.errors
# => ["Event type can't be blank"]

Events

Triggers an app_hook.created event.

Update an app hook

Update an app hook’s attributes. Only provided attributes are changed.

Request

Example
PUT /v1/app_hooks/:hook_id
{ "app_hook" :
  { "destination" : "https://example.com/webhook"
  }
}
hook=AuthRocket::AppHook.find 'hk_0v1zXKOfq1qKaFg2bLASQl'
hook.save destination: 'https://example.com/webhook'

Response

Example

Status: 200, with same body as Get an App Hook.

On success, returns same object as Get an App Hook.

On failure, returns false:

# => false
hook.errors
# => ["Destination can't be blank"]

Events

Triggers an app_hook.updated event.

Delete an app hook

Deletes an app hook.

Request

Example
DELETE /v1/app_hooks/:hook_id
hook=AuthRocket::AppHook.find 'hk_0v1zXKOfq1qKaFg2bLASQl'
hook.delete

Response

Example

Status: 204

On success, returns original object.

On failure, returns false.

Events

Triggers an app_hook.deleted event.

Questions? Find a Typo? Get in touch.