Webhooks

Webhooks allow your applications to receive real-time notifications whenever important events occur within VDSapps.

Setting Up Webhooks in RapIDadmin

To start receiving webhook notifications, you first need to configure them in the RapIDadmin interface.

  1. Navigate to RapIDadmin > API > Webhooks

  2. Click the Create button

  3. (Optional) Select an Application from the dropdown menu

    • Note: The application selector allows you to link webhooks to a specific application.

  4. Enter the notification URL where you want to receive the webhooks

  5. Generate a Signing Secret by clicking the Generate Secret button

    • Note: Store this secret securely as it will be used to verify the authenticity of incoming webhooks

  6. Select the events you want to subscribe to by checking the corresponding boxes

  7. Click the Save button

Important Considerations

  • Ensure your notification URL is publicly accessible and can handle POST requests

  • Keep your Signing Secret confidential to maintain the security of your webhook system

  • You can create multiple webhook configurations for different purposes or applications

Event Types

Each webhook notification includes:

  • A header called x-event-name that shows what type of event occurred

  • A JSON body containing the event details

The notifications differ based on the source:

  • EliteID notifications: Provide detailed updates about changes to person records and credentials

  • RapIDadmin notifications: Include information about print job status and details

x-event-name

Description

EliteId.Person.Created

New person record creation

EliteId.Person.Updated

Existing person record modification

EliteId.Person.Deleted

Person record removal

EliteId.PersonCredential.Created

Initial card issuance

EliteId.PersonCredential.Updated

Card reprint and smart card update

RapIDAdmin.PrintJob.Started

Print process initiation

RapIDAdmin.PrintJob.Complete

Successful print job completion

RapIDAdmin.PrintJob.Failed

Print job failure

JSON Payload Examples

EliteID Person Events

x-event-name: EliteID.Person.Created

{ "Id": " aff5ff4a-7775-4895-b999-99c9e70e1495", "IdNumber": "20020", "FirstName": "Jones", "FirstNamePreferred": null, "MiddleName": null, "LastName": "Kevin", "ModifiedTime": null, "Note": null, "NoteTime": null, "NoteCreatedBy": null, "SignatureId": null, "SignatureTime": null, "SignatureUri": null, "PhotoId": null, "PhotoTime": null, "PhotoUri": null, "CreationTime": "2024-10-04T15:38:53Z", "LastImportTime": null, "FieldValues": { "735ff460-00e5-4810-b7f4-1125a2418b00": "Student", "2ec1180e-1fbc-4b18-ba93-666041698261": "09", "c36a046f-3194-45a9-8889-b6ff7f1b80c6": "" } }

x-event-name: EliteID.Person.Updated

{ "Id": "aff5ff4a-7775-4895-b999-99c9e70e1495", "IdNumber": "20020", "FirstName": "KEVIN", "FirstNamePreferred": null, "MiddleName": null, "LastName": "JONES", "ModifiedTime": "2024-10-11T18:11:42Z", "Note": null, "NoteTime": null, "NoteCreatedBy": null, "SignatureId": null, "SignatureTime": null, "SignatureUri": null, "PhotoId": "0e92f9f0-e88e-4d67-9f2d-0b8c4f299046", "PhotoTime": "2024-10-04T15:40:21Z", "PhotoUri": "https://PHOTO_URI", "CreationTime": "2024-10-04T15:38:53Z", "LastImportTime": "2024-10-04T15:40:21Z", "FieldValues": { "2ec1180e-1fbc-4b18-ba93-666041698261": "09", "c36a046f-3194-45a9-8889-b6ff7f1b80c6": "kjones@email.com", "735ff460-00e5-4810-b7f4-1125a2418b00": "Student", } }

x-event-name: EliteId.Person.Deleted

{ "Id": "aff5ff4a-7775-4895-b999-99c9e70e1495", "IdNumber": "20020", "FirstName": "KEVIN", "FirstNamePreferred": null, "MiddleName": null, "LastName": "JONES", "ModifiedTime": "2024-10-11T18:11:42Z", "Note": null, "NoteTime": null, "NoteCreatedBy": null, "SignatureId": null, "SignatureTime": null, "SignatureUri": null, "PhotoId": "0e92f9f0-e88e-4d67-9f2d-0b8c4f299046", "PhotoTime": "2024-10-04T15:40:21Z", "PhotoUri": "https://PHOTO_URI", "CreationTime": "2024-10-04T15:38:53Z", "LastImportTime": null, "FieldValues": { "2ec1180e-1fbc-4b18-ba93-666041698261": "09", "c36a046f-3194-45a9-8889-b6ff7f1b80c6": "kjones@email.com", "735ff460-00e5-4810-b7f4-1125a2418b00": "Student" } }

EliteID Credential Events

x-event-name: EliteId.PersonCredential.Created

x-event-name: EliteId.PersonCredential.Updated

RapIDadmin Print Events

x-event-name: RapIDAdmin.PrintJob.Started

x-event-name: RapIDAdmin.PrintJob.Completed

x-event-name: RapIDAdmin.PrintJob.Failed

Field Descriptions

EliteID.Person Field Descriptions

The following table describes the fields that are included in Person webhook’s response body.

Field Name

Description

Field Name

Description

Id

Unique identifier for the person (UUID format)

IdNumber

Assigned identification number for the person

FirstName

Person's first name

FirstNamePreferred

Person's preferred first name (if different from FirstName)

MiddleName

Person's middle name

LastName

Person's last name

ModifiedTime

Timestamp of the last modification to the person's record

Note

Any additional notes about the person

NoteTime

Timestamp of when the note was last updated

NoteCreatedBy

Identifier of the user who created or last updated the note

SignatureId

Unique identifier for the person's signature

SignatureTime

Timestamp of when the signature was last updated

SignatureUri

URI to access the person's signature image

PhotoId

Unique identifier for the person's photo

PhotoTime

Timestamp of when the photo was last updated

PhotoUri

URI to access the person's photo. The link does not expire.

CreationTime

Timestamp of when the person's record was created

LastImportTime

Timestamp of the last time the person's data was bulk imported from an external system

FieldValues

Object containing custom field values, where the key is the field's UUID and the value is the field's content

Notes on FieldValues

The FieldValues object contains custom fields that may vary depending on your specific EliteID configuration.

The exact meaning and use of these custom fields will depend on your organization's setup.

EliteId.PersonCredential Field Descriptions

The following table describes the fields that are included in PersonCredential webhook’s response body.

Field Name

Description

Field Name

Description

PersonId

Unique identifier for the person (UUID format)

CardTemplateId

Unique identifier for the card template

CardTemplateName

Name of the card template

Created

Timestamp of the event

ExpirationDate

Card expiration date (if applicable)

IdNumber

Assigned ID number

Iso

Current ISO number (if applicable)

PreviousIso

Previous ISO number (if applicable)

ProxNumber

Current proximity card number (if applicable)

PreviousProxNumber

Previous proximity card number (if applicable)

ProxFacility

Current proximity facility code (if applicable)

PreviousProxFacility

Previous proximity facility code (if applicable)

Library

Current library number (if applicable)

Signature Verification

The webhook notification includes an x-signature header that contains a signature. The signature is generated server-side by creating an HMAC of the raw request body using SHA-256 and the Signing Secret as the key. To authenticate webhooks using signature verification, follow these steps:

  1. Retrieve the raw body of the request

  2. Extract the value from the x-signature header

  3. Compute the HMAC of the raw body using the SHA-256 hash function and the Signing Secret

  4. Compare the computed HMAC with the one provided in the x-signature header

Expected Webhook Events for Common Scenarios

This section outlines the sequence of webhook events you can expect for common operations within EliteID.

Note: Smart Card printing will generate two PersonCredential notifications. The second notification contains the updated smart card number.

EliteID API operations and bulk data imports do not generate webhook alerts.

A new person is added to the system

When a new person record is created:

  1. EliteId.Person.Created

A person's information is updated

When a person's information is modified in the system (Edits, Photos, Signatures, Notes):

  1. EliteId.Person.Updated

A person is deleted

When a person record is deleted in the system:

  1. EliteId.Person.Deleted

A person's first card is printed successfully

When a new card is printed for a person for the first time:

  1. EliteId.PersonCredential.Created

  2. RapIDAdmin.PrintJob.Started

  3. RapIDAdmin.PrintJob.Complete

A person's card is reprinted successfully

When an existing card is reprinted:

  1. EliteId.PersonCredential.Updated

  2. RapIDAdmin.PrintJob.Started

  3. RapIDAdmin.PrintJob.Complete

A person’s card fails to print

When a card does not print:

  1. EliteId.PersonCredential.Updated

  2. RapIDAdmin.PrintJob.Failed

A (Smart) card is printed successfully

When a card associated with a Smart template is printed:

  1. EliteId.PersonCredential.Created

  2. RapIDAdmin.PrintJob.Started

  3. EliteId.PersonCredential.Updated

  4. RapIDAdmin.PrintJob.Complete

A (Smart) card is reprinted successfully

When a card associated with a Smart template is reprinted:

  1. EliteId.PersonCredential.Updated

  2. RapIDAdmin.PrintJob.Started

  3. EliteId.PersonCredential.Updated

  4. RapIDAdmin.PrintJob.Complete