The why and how of Nametag webhooks
Nametag offers a number of logging webhooks that emit JSON-formatted data that you can ingest into your SIEM system and process as part of your security and monitoring practices.
The webhooks related to end-user actions are documented at https://getnametag.com/docs/api/#webhooks and the webhooks related to administrative actions in the Nametag console are documented at https://getnametag.com/docs/api/#audit-api
That documentation is the technical documentation and describes the “what” more than the “how” and “why”; here we will try to describe how and why you would use each of these webhooks.
Configuring and enabling webhooks
Nametag’s webhook configuration is done in the Webhooks section of the Configure page of https://console.nametag.co. Clicking “Add a webhook” will show a configuration panel that looks like this:
The fields in the webhook configuration are:
-
Enabled: is this webhook going to be sent or not; the default is that this is off, so make sure to toggle it on when you are ready to send the webhooks
-
Delivery URL: this is the URL that will receive the webhook; the documentation for your SIEM will tell you what this should be. Nametag has some examples for Splunk and Crowdstrike SIEMs
If the webhook URL is a Crowdstrike URL the JSON body will be wrapped so that Crowdstrike can ingest the data.
If the webhook URL is a Slack URL, the JSON body will be wrapped so that Slack can ingest the data.
-
Authorization header: if your SIEM requires an authorization header, enter it here
-
Events: You should not enable the webhook for “A user completes self-service account recovery” for the same webhook destination as the other webhooks. That webhook is not a logging webhook and improper use will prevent account recovery from working. There is more information on this later in this document.
The Shared Secret on the webhook configuration page can be used to validate that the webhook is being sent by Nametag and was unaltered in transit. For more on this see https://getnametag.com/docs/api/#webhooks.
The Nametag console displays the 50 most recent webhooks and their status. Clicking on a request ID in the Recent deliveries table will show you what was sent, what the status was, and any response. This can be very helpful in debugging any problems with webhook deliveries.
You may configure several webhook destinations if needed. If you enable the webhook for “A user completes self-service account recovery” in addition to the logging webhooks, you will have at least two different webhooks, one for the processing of the account recovery information and one for the log messages.
If you do not yet have a webhook receiver configured, you can test the webhooks using test sites available on the internet, one example of these sites is https://webhook.site.
Webhooks for logging end-user actions
Nametag offers three webhooks for logging end-user actions:
- the Share event webook https://getnametag.com/docs/api/#share-event
- the Revoke event webhook https://getnametag.com/docs/api/#revoke-event
- the Request event webhook https://getnametag.com/docs/api/#request-event
Share and Revoke webhooks
The Share and Revoke webooks do not contain any personally-identifiable information (PII) and are primarily intended to be combined with other information (either from Nametag or from other sources) as a record of data sharing and revocation. The data shared in those webhooks is nearly the same and a Share event can be correlated with a Revoke event using the subject field. The subject field is an identifier that is stable and unique to the combination of an end-user and an environment.
An example of a Share webhook is (for the latest format see https://getnametag.com/docs/api/#share-event):
{
"event_type": "share",
"subject": "vkljipkaio2ap663do54r5fp2a@5lsqfg1luqzb9s.nametag.co",
"request": "f9cbc40a-5da2-4f1c-84a6-f8e097fca03c",
"env_name": "Live",
"org_name": "My Company",
"claims": [
"name"
]
}
The event_type is share for the Share webhook and reject for the Revoke webhook and there is no request for the Revoke webhook, because it is initiated by the end-user in the Nametag mobile app, not from a request by a third party.
Using the subject value and an API key with access to the environment encoded in the subject string, you can retrieve more information, including PII, from the Nametag API. See https://getnametag.com/docs/api/#people-api and https://getnametag.com/docs/api/#get-a-request for more information.
If you have a requirement for event logging and cannot store PII in your logging system, these two events are good choices. Using an API key you can augment the data from these events with IP addresses, statuses, who the requester was, what browser was used, as well as more personal information about the end-user.
The Request webhook
The Request webhook emits much more detailed information than the Share and Revoke webhooks do, and may include PII.
The Request webhook is sent for many events, including every stage of the request process. The The event types are listed at https://getnametag.com/docs/api/#request-event. You can see similar behavior in the Nametag console as the request is generated, opened, the QR code is scanned, the end-user’s ID is scanned and their selfie is taken, and when the end-user consents to share information with you. This can generate a lot of traffic to your SIEM platform, including information containing PII; for those reasons it is common to have an intermediate processing step that removes or elides certain information before the data is ingested.
The details of the Request webhook are the same as for the Request API endpoint; these details are available at https://getnametag.com/docs/api/#get-a-request. An example of this data is (for the latest format see https://getnametag.com/docs/api/#request-event):
{
"event_type": "request",
"event": "request_created",
"request": {
"id": "660de718-8ccd-498d-bdeb-4a722fca708c",
"created_at": "2021-01-01T00:00:00Z",
"updated_at": "2021-01-01T00:00:00Z",
"expires_at": "2021-01-11T00:00:00Z",
"ticket": "qznqhsbyqmoose",
"link": "https://nametag.co/i/qznqhsbyqmoose",
"phone": "+12025551212",
"env": "b8riks6ax4udyau",
"template": "support_request",
"label": "ticket #4213",
"scopes": ["nt:legal_name"],
"claims": ["name"],
"status": "pending",
"progress": "created",
"subject": "bhcp6ml7uhzsg4qadudrfoaxn4@b8riks6ax4udyau.nametag.co",
"subject_text": "Alice K. Smith",
"requester": "6b237b56-97bc-4dbd-85fb-f4cc16b0c91b",
"requester_text": "Bob Jones",
"properties": {
"phone": "+12025551212",
"legal_name": "Alice Catherine Smith",
"legal_first_name": "Alice",
"legal_last_name": "Smith",
"name": "Alice Smith",
"first_name": "Alice",
"last_name": "Smith",
"birth_date": "1989-03-23",
"email": "alice@example.com",
"unverified_email": "alice@example.com",
"age_over_18": true,
"age_over_21": true,
"profile_picture": "https://nametagusercontent.com/profile-pictures/6465/6d6f/64656d6f2d30623731663638333862303462353662373735353765626330646332313865663761313535313937663866373039336638323566663862363632396538336634",
"address": "123 Main St, Ann Arbor, MI 48104",
"govtid": {
"type": "passport",
"issuer": "VA.USA",
"document_number": "K3521558123",
"expiration": "2025-12-31"
},
"govtid_Expired": true,
"ip_location": true
},
"mobile": {
"os": "iOS/17.6.1; iPhone 14 Pro Max",
"version": "4.18.3-55",
"ios": true,
"android": false,
"full_app": false,
"app_clip": true,
"instant_app": false,
"remote_address": "200.123.43.23",
"remote_address_location": {
"latitude": 42.2807,
"longitude": -83.7801,
"city": "Ann Arbor",
"subdivision": "Michigan",
"country": "United States",
"residential": true,
"business": false,
"po_box": false
}
},
"browser": {
"user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/88.0.4324.150 Safari/537.36",
"remote_address": "200.123.43.23",
"remote_address_location": {
"latitude": 42.2807,
"longitude": -83.7801,
"city": "Ann Arbor",
"subdivision": "Michigan",
"country": "United States",
"residential": true,
"business": false,
"po_box": false
}
},
"details": {
"selfie": {
"annotated_image": "https://nametagusercontent.com/profile-pictures/c01e/c034/c01ec03417548c59ece89462bbebdc39e0f467d37f5f3fd35d24596b814b60edb2837c80",
"app_attestation_confirmed_at": "2021-01-01T00:00:00Z",
"app_attestation_ok": true,
"depth_map": "https://nametagusercontent.com/profile-pictures/ffce/303a/ffce303a39df68872e089f7bdd56e9c62433034a555153f93657d01c40b654a43f19ef11",
"depth_map_confidence": "0.997",
"depth_map_ok": true,
"face_match_confidence": "0.999",
"face_match_ok": true,
"selfie_chain_confidence": "0.998",
"selfie_chain_count": 2,
"selfie_chain_ok": true,
"selfie_status_ok": true,
"taken_at": "2021-01-01T00:00:00Z"
},
"document": {
"address_location": {
"latitude": 42.2807,
"longitude": -83.7801,
"city": "Ann Arbor",
"subdivision": "Michigan",
"country": "United States",
"residential": true,
"business": false,
"po_box": false
},
"annotated_image": "https://nametagusercontent.com/profile-pictures/c01e/c034/c01ec03417548c59ece89462bbebdc39e0f467d37f5f3fd35d24596b814b60edb2837c80",
"app_attestation_confirmed_at": "2021-01-01T00:00:00Z",
"app_attestation_ok": true,
"barcode": {
"property1": "string",
"property2": "string"
},
"cardcheck_confidence": 0.993,
"cardcheck_ok": true,
"scanned_at": "2021-01-01T00:00:00Z",
"structure_confidence": 0.942,
"structure_ok": true,
"template_confidence": 0.947,
"template_ok": true,
"authority_verification": {
"authority": "IN.UIDAI",
"authority_name": "Unique Identification Authority of India (Aadhaar)",
"online_verified": true,
"digital_signature_verified": true,
"profile_photo_verified": true
}
},
"device": {
"app_integrity_ok": true,
"app_version": "4.18.3-55",
"device_integrity_confirmed_at": "2021-01-01T00:00:00Z",
"device_integrity_ok": true,
"device_os": "iOS/17.6.1; iPhone 14 Pro Max",
"device_public_key": "85:e0:dd:3d:6c:ca:74:ef:e6:94:30:4c:9f:86:23:09",
"device_user_agent": "nametag.hello.Clip/4.18.3-55; iOS/17.6.1; iPhone 14 Pro Max",
"device_verified_at": "2021-01-01T00:00:00Z",
"ip_address": "200.123.43.23",
"ip_location": {
"latitude": 42.2807,
"longitude": -83.7801,
"city": "Ann Arbor",
"subdivision": "Michigan",
"country": "United States",
"residential": true,
"business": false,
"po_box": false
}
},
"privacy": {
"biometric_consent_provided_at": "2021-01-01T00:00:00Z",
"data_sharing_consent_provided_at": "2021-01-01T00:00:00Z",
"processing_region": "us",
"storage_region": "eu",
"aadhaar_storage_region": "string"
},
"completed_at": "2021-01-01T00:00:00Z",
"scopes_expire_at": "2021-01-01T00:00:00Z",
"claims_expire_at": "2021-01-01T00:00:00Z",
"revoked_at": null,
"reject_reason": "device",
"appeal": true,
"appeal_completed_at": "2021-01-01T00:00:00Z",
"appeal_reject_category": "fraud",
"appeal_reject_reason": "presentation_fraud",
"integrity_ok": true,
"account": {
"id": "b8962843-29a5-4302-90b4-2090af83fc31",
"directory_kind": "azure-ad",
"email": "alice@example.com",
"env_id": "b8riks6ax4udyau",
"env_name": "Live",
"name": "Alice Smith",
"photo": "string",
"have_birth_date": true,
"birth_date": "1989-03-23"
},
"is_self_service": true,
"deletion_block_reporter": "Nametag"
},
"is_known_user": true,
"photo": "string",
"external_ids": [
"string"
],
"marked_for_deletion_after": "2019-08-24T14:15:22Z"
}
}
Webhooks for logging administrative actions
The Audit webhook and API endpoint
Whenever an administrative change is made to a configuration of Nametag or to data that Nametag holds, a webhook is sent containing the details of the change and who made it. Because there are many things that can change, there are many event types that you will see and each event type may contain data that is unique to itself. The event types and what they contain are documented in the table at https://getnametag.com/docs/api/#audit-api
In addition to a webhook, the events are also available via the Nametag API (also documented at https://getnametag.com/docs/api/#audit-api).
An example of the audit webhook format is below; note that everything after the first object is optional and only present if something was changed. For example, if the change does not involve the creation of a new enviroment, then the "env_created" object will not be present in the webhook body (for the latest format see https://getnametag.com/docs/api/#audit-api).
{
"events": [
{
"id": "string",
"time": "2019-08-24T14:15:22Z",
"trace": "string",
"remote_addr": "string",
"user_agent": "string",
"org": "string",
"env": "string",
"principal": {
"role": "limited",
"org_member": "string",
"api_key": "string",
"impersonator": "string",
"subject": "string"
},
"env_created": {
"request": {
"sandbox": false
},
"response": {
"id": "d8x3pnsedk0tbm"
}
},
"env_updated": {
"request": {
"name": "Live",
"public_name": "ACME, Inc.",
"description": "string",
"terms_of_service_url": "string",
"callback_urls": [
"http://example.com"
],
"send_in_progress_email": true,
"send_completed_email": true,
"send_request_cancelled_email": true,
"send_revoked_email": true,
"send_link_opened_email": true,
"visit_url": "string",
"remove_webhooks": [
"string"
],
"add_webhooks": [
{
"id": "7989f1de-d0a9-403e-a227-4f5bb4c6e9e4",
"url": "https://example.com/webhook",
"enabled": true,
"events": ["recover"],
"authorization_header": "Bearer 1234567890"
}
],
"update_webhook": {
"id": "string",
"url": "string",
"enabled": true,
"events": [
"share"
],
"authorization_header": "string"
},
"theme": {
"accept_button_color": "0091FF",
"background_color_1": "794744",
"background_color_2": "746D50",
"background_color_3": "4A4A67",
"background_color_4": "684848"
},
"recovery_microsite": "nametag.example.com",
"recovery_microsite_presign_required": "false",
"send_request_rejected_unusable_email": false,
"send_request_rejected_fraud_email": false,
"storage": {
"s3_bucket_us": "my-company-bucket-us",
"s3_bucket_eu": "my-company-bucket-eu",
"s3_bucket_in": "my-company-bucket-in",
"aws_role_arn": "arn:aws:iam::123456789:role/NametagStorage",
"azure_blob_us": "https://example.blob.core.windows.net/ntedceastus?sp=racwdli&st=2024-11-04T18:28:43Z&se=2026-11-05T02:28:43Z&spr=https&sv=2022-11-02&sr=c&sig=pR0z4OGuZpE1VtQOXuqukyVkfDcPQt5xLJRG1fgduTU%3D",
"azure_blob_eu": "https://example.blob.core.windows.net/ntedceastus?sp=racwdli&st=2024-11-04T18:28:43Z&se=2026-11-05T02:28:43Z&spr=https&sv=2022-11-02&sr=c&sig=pR0z4OGuZpE1VtQOXuqukyVkfDcPQt5xLJRG1fgduTU%3D",
"azure_blob_in": "https://example.blob.core.windows.net/ntedceastus?sp=racwdli&st=2024-11-04T18:28:43Z&se=2026-11-05T02:28:43Z&spr=https&sv=2022-11-02&sr=c&sig=pR0z4OGuZpE1VtQOXuqukyVkfDcPQt5xLJRG1fgduTU%3D"
}
}
},
"env_deleted": {
"empty": true
},
"env_logo_uploaded": {
"kind": "string"
},
"env_logo_deleted": {
"kind": "string"
},
"template_created": {
"request": {
"name": "Customer support request",
"headline": "{{.PublicName}} wants to confirm your identity",
"qr_headline": "{{.PublicName}} would like to verify your identity.",
"expiration_text": "Expires in {{ .TTL }}",
"accept_text": "Confirm identity with {{ .PublicName }}",
"accepted_text": "Confirmed identity with {{ .PublicName }}",
"install_message_sms": "Confirm identity with {{.PublicName}}. Click this link to share: {{.Link}}",
"is_default": true,
"scope_definitions": [
{
"scope": "nt:name",
"restrict_email_domains": ["example.com"]
}
],
"scopes_expire_in": 3600,
"claim_definitions": [
{
"claim": "name"
}
],
"claims_expire_in": 3600,
"enabled": true,
"require_selfie_reverification": true,
"enable_selfie_smile": false,
"qr_custom_text": "We use Nametag to make sure that it's really you. Scan this QR code, then follow the instructions to verify your identity using your smartphone."
},
"response": {
"id": "d8x3pnsedk0tbm"
}
},
"template_updated": {
"template": "string",
"request": {
"name": "Customer support request",
"headline": "{{.PublicName}} wants to confirm your identity",
"qr_headline": "{{.PublicName}} would like to verify your identity.",
"expiration_text": "Expires in {{ .TTL }}",
"accept_text": "Confirm identity with {{ .PublicName }}",
"accepted_text": "Confirmed identity with {{ .PublicName }}",
"install_message_sms": "Confirm identity with {{.PublicName}}. Click this link to share: {{.Link}}",
"is_default": true,
"scope_definitions": [
{
"scope": "nt:name",
"restrict_email_domains": ["example.com"]
}
],
"scopes_expire_in": 3600,
"claim_definitions": [
{
"claim": "name"
}
],
"claims_expire_in": 3600,
"enabled": true,
"require_selfie_reverification": true,
"enable_selfie_smile": false,
"ephemeral_data_mode": "logout",
"qr_custom_text": "We use Nametag to make sure that it's really you. Scan this QR code, then follow the instructions to verify your identity using your smartphone."
}
},
"template_deleted": {
"template": "string"
},
"env_webhook_secret_updated": {
"empty": true
},
"org_updated": {
"request": {
"name": "string",
"saml": {
"groups": [
{
"name": "string",
"role": "limited",
"envs": [
"string"
]
}
]
},
"allowed_ip_addresses": [
"string"
],
"console_session_ttl_minutes": 0,
"console_token_ttl_minutes": 0
}
},
"org_member_invited": {
"request": {
"email": "user@example.com",
"role": "limited",
"envs": [
"string"
]
}
},
"org_member_removed": {
"org_member": "string"
},
"org_member_updated": {
"org_member": "string",
"request": {
"role": "limited",
"envs": [
"string"
]
}
},
"apikey_created": {
"request": {
"name": "string",
"enabled": true,
"envs": [
"string"
],
"role": "limited"
},
"response": {
"id": "3p0wjj3b7vyia5",
"key": "3p0wjj3b7vyia5V2JCNoO3TqHpjT"
}
},
"apikey_updated": {
"apikey": "string",
"request": {
"name": "string",
"enabled": true,
"role": "limited",
"envs": [
"string"
]
}
},
"apikey_deleted": {
"apikey": "string"
},
"request_created": {
"request": {
"env": "b8riks6ax4udyau",
"scopes": ["nt:legal_name", "nt:address"],
"claims": ["name"],
"template": "support_request",
"expires_at": "2021-01-01T00:00:00Z",
"phone": "+12025551212",
"whatsapp": "+12025551212",
"label": "ticket #4213",
"external_ticket": "JIRA-4213",
"ttl": "3600"
},
"response": {
"id": "8e9ac675-cda5-4a8b-b41f-8fcc974c6bc2",
"status": 410,
"env": "ypup63a4jvtdy7",
"scopes": ["nt:legal_name"],
"claims": ["legal_name"],
"template": ["support_request"],
"link": "https://nametag.co/i/otrvsdd7oqj9ac",
"phone": "+12025551212",
"label": "ticket #4213",
"expires_at": "2021-01-01T00:00:00Z"
}
},
"request_updated": {
"request_id": "string",
"request": {
"label": "ticket #4213"
}
},
"request_canceled": {
"request_id": "string"
},
"account_updated": {
"directory": "string",
"account": "string",
"request": {
"subject": "string",
"birth_date": "string"
}
},
"account_photo_uploaded": {
"directory": "string",
"account": "string"
},
"directory_created": {
"request": {
"env": "string",
"kind": "azure-ad",
"credentials": {
"partition": "api-33091yc9.duosecurity.com",
"account": "QVFDLYPXMALI29XS00ZB",
"secret": "cv9wJSC10XDFRGY5L9DcgHuNtR76vM8kuB1sDCpc"
}
},
"response": {
"id": "8cf80c8a-6e83-40cd-ab77-605e8773e937",
"redirect_url": "string"
}
},
"directory_updated": {
"directory": "string",
"request": {
"authenticate_policy": {
"groups": [
{
"group": {
"directory_immutable_identifier": "string",
"name": "string"
},
"policy": "name_match"
}
],
"default": "name_match"
},
"password_policy": {
"groups": [
{
"group": {
"directory_immutable_identifier": "string",
"name": "string"
},
"policy": "name_match"
}
],
"default": "name_match"
},
"mfa_policy": {
"groups": [
{
"group": {
"directory_immutable_identifier": "string",
"name": "string"
},
"policy": "name_match"
}
],
"default": "name_match"
},
"unlock_policy": {
"groups": [
{
"group": {
"directory_immutable_identifier": "string",
"name": "string"
},
"policy": "name_match"
}
],
"default": "name_match"
},
"temporary_access_pass_policy": {
"groups": [
{
"group": {
"directory_immutable_identifier": "string",
"name": "string"
},
"policy": "name_match"
}
],
"default": "name_match"
},
"temporary_access_pass_lifetime_minutes": 0,
"temporary_access_pass_reusable": true,
"birth_date_hmac_secret": "string"
}
},
"directory_deleted": {
"directory": "string"
},
"directory_authorized": {
"directory": "string"
},
"directory_set_credentials": {
"directory": "string"
},
"console_signin": {
"saml_response": "string",
"relay_state": "string",
"saml": true,
"email": true,
"nametag": true
},
"console_singin_configure_email": {
"empty": true
},
"console_singin_configure_saml": {
"empty": true
},
"cli_signin": {
"session": "string"
},
"oauth2_pushed_authorization_event": {
"request": {
"client_id": "string",
"client_secret": "string",
"redirect_uri": "string",
"state": "string",
"scope": [
"nt:name"
],
"claim": [
"name"
],
"response_type": "code",
"response_mode": "fragment",
"code_challenge": "string",
"code_challenge_method": "plain",
"email_hint": "user@example.com",
"template": "string",
"return": ""
},
"response": {
"request_uri": "string",
"expires_in": 0
}
},
"oauth2_authorize": {
"request": {
"client_id": "string",
"redirect_uri": "string",
"state": "string",
"scope": [
"nt:name"
],
"claim": [
"name"
],
"response_type": "code",
"response_mode": "fragment",
"code_challenge": "string",
"code_challenge_method": "plain",
"email_hint": "user@example.com",
"template": "string",
"return": ""
},
"response": {
"error_message": "string",
"redirect_uri": "string",
"env_name": "string",
"qrcode": "string",
"install_ticket": "string",
"request": "string",
"session_token": "string",
"app_clip_experience": "string",
"return": ""
}
},
"oauth2_v2_authorize": {
"request": {
"request_uri": "string"
},
"response": {
"error_message": "string",
"redirect_uri": "string",
"env_name": "string",
"qrcode": "string",
"install_ticket": "string",
"request": "string",
"session_token": "string",
"app_clip_experience": "string",
"return": ""
}
},
"oauth2_request_canceled": {
"request": "string"
},
"oauth2_token": {
"request": {
"grant_type": "authorization_code",
"client_id": "string",
"client_secret": "string",
"redirect_uri": "string",
"code": "string",
"code_verifier": "string"
},
"response": {
"access_token": "string",
"refresh_token": "string",
"id_token": "string",
"scope": "string",
"claims": "string",
"expires_in": 0,
"token_type": "Bearer",
"subject": "string"
}
},
"entra_eam_authorize": {
"directory": "string",
"request": {
"client_id": "string",
"client_request_id": "string",
"scope": "string",
"response_type": "string",
"response_mode": "string",
"redirect_uri": "string",
"nonce": "string",
"state": "string",
"claims": "string",
"id_token_hint": "string"
},
"response": {
"state": "string",
"oauth2_server": "string",
"oauth2_client_id": "string",
"oauth2_redirect_uri": "string",
"oauth2_template": "string"
}
},
"entra_eam_finish": {
"directory": "string",
"request": {
"state": "string",
"error": "string",
"code": "string"
},
"response": {
"error": "string",
"redirect_uri": "string",
"oauth2_state": "string",
"binding_failed": true,
"id_token": "string"
}
},
"okta_eam_authorize": {
"directory": "string",
"request": {
"client_id": "string",
"scope": "string",
"response_type": "string",
"redirect_uri": "string",
"state": "string",
"claims": "string",
"login_hint": "string"
},
"response": {
"state": "string",
"oauth2_server": "string",
"oauth2_client_id": "string",
"oauth2_redirect_uri": "string",
"oauth2_template": "string"
}
},
"okta_eam_finish": {
"directory": "string",
"request": {
"state": "string",
"error": "string",
"code": "string"
},
"response": {
"error": "string",
"redirect_uri": "string",
"oauth2_state": "string",
"binding_failed": true,
"request_timeout": true,
"id_token": "string",
"code": "string"
}
},
"people_compare": {
"request": {
"expectations": [
{
"scope": "nt:name",
"claim": "name",
"value": "string"
}
]
},
"response": {
"confidence": 0.1,
"comparisons": [
{
"scope": "nt:name",
"claim": "name",
"expected": "string",
"actual": "string",
"match": true,
"match_confidence": 0.1
}
]
}
},
"selfie_compare": {
"subject": "string",
"response": {
"match": true,
"confidence": 0.1
}
},
"sharing_revoked": {
"subject": "string",
"scopes": [
"nt:name"
],
"claims": [
"name"
]
}
}
]
}
A webhook for implementing your own policies
The Recovery webhook
In addition to the three end-user event webhooks and one administrative event webhook, there is a fifth webhook that is not intended for logging at all (and, in fact, is likely to cause account recovery to fail if you enable it for logging). This is the Recover event webhook. (See more at https://getnametag.com/docs/api/#recover-event)
The Recover event webhook is for you to implement policy on account recovery (password reset, MFA reset, account unlock, etc) in any way you require, without involvement from Nametag.
The Recover webhook is synchronous and the account recovery process is paused until Nametag gets a response from your webhook receiver. That response must be a 200 OK regardless of whether the decision is positive or negative. To indicate a negative response, include a JSON element at the top-level called deny_user_message; the value of that element will be displayed to the end-user. The process is shown in the image below.
Note that Step 5 is opaque to Nametag and may also contact other internal or external services that you rely on for additional information needed to make the decision of whether or not the end-user can reset some aspects of their account.
An example JSON body posted to your webhook receiver is (for the latest format see https://getnametag.com/docs/api/#recover-event):
{
"event_type": "recover",
"subject": "string",
"language": "string",
"directory": "string",
"external_id": "string",
"action": "password-reset",
"org_name": "string",
"env_name": "string",
"date": "2019-08-24T14:15:22Z"
}
and the response from the webhook receiver to Nametag may look like this:
{
"deny_user_message": "string"
}
or may be empty, but must return a 200 OK response or the end-user will not be able to complete the account recovery process.
How to use webhook data
Nametag can produce a significant amount of detailed data to add to your existing SIEM data and while the most important advice will come from your security team, there are a few things you may consider.
-
Capture the IP addresses from the Request webhook
There are two IP addresses in the Request webhook, one for the device that opens the request and one for the device that scans the ID and fulfills the request. Those IP addresses can be correlated with IP addresses that appear elsewhere in your SIEM to develop a picture of the behavior of a bad actor.
These IP addresses are in
mobile.remote_addressandbrowser.remote_addressin the JSON body of the Request webhook. -
Note the reasons for rejection
You may want to alert or report on why ID validations are rejected; those reasons are in the
detailsobject of the Request webhook. There are specifics in each of theselfie,document, anddevicesub-objects, but the most interesting things are at the top level of thedetailsobject:-
reject_reasonis the reason the Nametag Secure Processing Engine (NSPE) automatically stopped the identity verification process -
appealis a boolean indicating whether or not the end-user appealed the decision of the NSPE -
appeal_reject_categoryis one of eitherfraudorunusable;unusablemeans that the document was damaged, poorly lit, had too much glare, or was otherwise unreadable. If Nametag believes that some part of the identity verification process is fraudulent, the category will befraud -
appeal_reject_reasonis one ofpresentation_fraud,injection_fraud,repeat_fraud,selfie_liveness,misc_fraudfor fraudulent attempts, andscreen,paper,non_compliant,redacted,damaged,unacceptable_doc_type,selfie_mismatch,blurry,glare,out_of_frame,occluded,unverified_device, orshared_devicefor attempts that presented data that isunusable.
-
-
Note the rate of request generation for a each agent
The internal Nametag ID of the agent who generated the request is in the Request webhook, and monitoring the rate of occurrence of that ID can indicate that someone is generating an excessive number of requests. That can be an indication of a compromised agent account and a bad actor trying to figure out how to circumvent Nametag. You may also be able to correlate this with SIEM information from your service desk tools.
-
Consider each of the categories of administrative change and alert on those of interest to you
Not everyone will care about all of the categories of administrative change, but some of them - API Key generation, for example - may be of higher interest. See https://getnametag.com/docs/api/#list-2 for the list of categories
A note on storing PII in your logging system
It is very important that you are cautious about storing PII; there are global laws dictating what can be stored, where it must be stored, and when and how it must be deleted.
If you choose to store PII in your SIEM, please be aware of the laws that apply to each of your end-users. An incomplete list of these are US federal and state data privacy laws, GDPR in Europe, and data residency laws in India and China.
If your SIEM stores data in only one jurisdiction and you do not have a way of expunging data from it, it is possible that you won’t be compliant with all data residency and protection laws. Nametag strongly suggests consulting with data privacy lawyers or other experts before storing any data that might be considered PII.