How to Create a Trigger Webhook in the ID Management System (IDMS)

Before You Begin: Open the Webhook Creation Page

• Log into your IDMS admin account.
• In the left-hand navigation panel, click ‘Integrations’.
• Select ‘Webhooks’ from the options.
• Click the ‘Create A Webhook’ button to begin the setup process. The setup has three steps: Webhook Type, Data Mapping, and Authorization.

Step 1: Webhook Type

• Enter a ‘Webhook Name’ to serve as an internal label that helps you identify the webhook in the webhooks table.
• Select ‘Trigger’ as the webhook type. A trigger webhook automatically sends data from the IDMS to an external system when an event occurs.
• Choose one or more event categories: Card Record Events, Card Status Events, Card Print Events, Barcode Scanner Events, or Card Moderation Events. Hover over a category to see all of the triggers it includes.
• Choose which card record groups this webhook applies to:
  • All Card Record Groups (default): the webhook fires for events in every card record group.
  • Specific Card Record Groups: select a card record group from the dropdown. The webhook fires only for events in that group.
• Once configured, click ‘Next’ to continue.

Step 2: Data Mapping

• A summary at the top of the step shows your webhook name, webhook type, and selected events.
• The ‘Webhook Events’ section lists the event values included in the categories you selected. To leave out an event value you don’t need, click the trash icon next to it.

Map Your Webhook Data Fields

Below the ‘HTTP Headers’ section, use the ‘Webhook Data Mapping’ section to choose the card data you want to send in the request body.

• Every available ID123 variable for your card record group is mapped by default. In the ‘Payload Variable’ column, change any name to match what your external application expects.
• To remove a field you don’t want to send, click the trash icon next to it.
• To add a field back, select ‘Add New Data Mapping Row’ search for the ID123 variable by name, and click ‘Add’.
• To change your events or card record groups, select ‘Back’ to return to Step 1. When your mapping is complete, press ‘Next’.

Step 3: Authorization

• Type in your ‘Trigger URL.’ This is the endpoint URL of the external system that will receive the webhook data.
  • Make sure the receiving system is ready to accept webhook requests at this URL.
• Select the ‘Authorization Header Type’ your receiving system requires:
  • None: no authorization header is sent with the request.
  • API Key: the Authorization Header Name is pre-filled with X-Api-Key. Enter the API key from your receiving system in the Authorization Header Value field.
  • OAuth 2.0: enter the Client Secret, Client ID, Supported Scope, and Access Token URL from your receiving system, and confirm the Trigger API URL. The IDMS uses these credentials to get an access token and sends it in the Authorization header as Bearer <access_token>. Click Test Connection to check the credentials before you save.
• Click ‘Save’. Your new trigger webhook appears on the Webhooks page.