Looking to automate tasks in real time? With an action webhook, an external application (such as your SIS, HR system, or CRM) can tell the ID Management System (IDMS) to perform an action automatically, like creating, updating, or revoking a card record. This guide walks you through how to create an action webhook in ID123’s IDMS platform.
What is a Webhook?
A webhook is a method of communication between two web applications. When a specific event happens in one system, it sends an HTTP request (usually POST) to a specified Action URL in another system. This enables real-time data exchange without needing manual input.
What is an Action Webhook?
An action webhook lets an external system make changes in IDMS. When an event happens in your third-party application (for example, a new student is enrolled or an employee leaves), that application sends an HTTP request to the webhook’s Action URL. IDMS receives the request and performs the selected action, such as adding, editing, or deleting a card record or changing its card status.
This is the reverse of a trigger webhook, where an event in IDMS sends data out to an external system. Action webhooks are ideal for keeping card records in sync with your source system without manual data entry.
Getting Started: Open the Webhooks Page
- Log in to your IDMS admin account.
- From the left-hand navigation menu, click on “Integrations”.
- Select “Webhooks” from the submenu.
- Click the Create A Webhook button in the top right corner. This opens a 3-step setup: Webhook Type, Data Mapping, and Authorization.
Step 1: Choose a Webhook Type
- Enter an internal name for the webhook. This label is shown in the webhooks table. A default name is filled in automatically, and you can change it (up to 200 characters).
- Under Webhook Type, select Action.
- Under Select which actions should occur after the trigger fires?, choose one or more event categories: Card Record Events, Card Status Events, Card Print Events, or Messaging Events. Hover over an event type to see the actions it includes. (For example, Card Record Events include Add, Edit, Delete, and Send Card Invitation.) *Note: For a full list of supported events, refer to the Action/Trigger Webhook Event Definitions knowledge base article.*
- Choose which card record group(s) incoming requests should go to by selecting ‘All’ groups or ‘Specific’ groups.
- All Card Record Groups (the default): the webhook applies to every card record group.
- Specific Card Record Groups: route records to different groups based on values in the incoming payload, using a single Action URL.
- Build each routing rule in the format: IF [Payload Variable] equals [Value] THEN route to [Target Card Record Group].
- Click + Add Routing Rule to add more rules. Rules are evaluated top to bottom, and the first matching rule determines the target group.
- Set a fallback under IF NO RULES MATCH route to by selecting the card record group that should receive records that don’t match any rule.
- In either instance, you must choose how you want to identify the card record in the group by choosing a Card ID or Unique Identifier. IDMS uses this value from the incoming request to find the card record to act on, so your external system only needs to send one of them.
- Select Next.
Step 2: Map Webhook Data
- A summary bar at the top shows the webhook name, type, and selected events. To change any of these, click Back.
- Webhook Events: This table maps the event values your external system sends to the events IDMS understands.
- Rows are pre-filled based on the event types you selected in Step 1. For Card Record Events, this includes the
eventvariable with the valuesadd,edit, anddelete, plus thesend-invitationandforce-send-invitevariables with the valuetrue. - Edit the Payload Variable and Payload Value columns to match what your external system sends. The ID123 Variable and ID123 Value columns can’t be edited.
- To remove an event you don’t need, click its trash icon.
- Rows are pre-filled based on the event types you selected in Step 1. For Card Record Events, this includes the
- Webhook Data Mapping: This table maps the fields in your external system’s payload to ID123 card record variables.
- Rows are pre-filled with common variables such as
card-id,unique-identifier,expiration-timestamp,card-status,recipient-email,first-name, andlast-name. - Edit each Payload Variable to match the field name your external system uses. Make sure the identifier you chose in Step 1 (Card ID or Unique Identifier) is mapped.
- To remove a variable you don’t need, click its trash icon. To add one back, click + Add New Data Mapping Row (this button appears once at least one variable has been removed), search for the variable, and click Add.
- When your mapping is complete, click Next.
- Rows are pre-filled with common variables such as
Step 3: Add an Authorization Header
- Authorization Header Type: Choose how the IDMS should verify requests sent to the Action URL.
- None: Requests don’t need an authorization header.
- API Key: Requests must include an API key header. The Authorization Header Name is set to
X-Api-Keyand can’t be changed. For Authorization Header Value, select one of your API keys from the dropdown. API keys are managed under Integrations > API Keys.
- If you chose API Key, make sure your external system sends the
X-Api-Keyheader with the selected key in every request. - Click Save.
Step 4: Copy Action URL
- A confirmation popup appears with your Action URL. Click Copy URL and add it to your external system’s webhook or automation settings. This is the endpoint your external system calls to tell IDMS to perform an action. You can also find the Action URL later on the Webhooks page.
Once your action webhook is saved, IDMS will listen for requests sent to the Action URL. Each time your external application calls it, IDMS performs the selected action on the matching card record, routing it to the correct card record group based on your routing rules. This allows for efficient, real-time integration between your external applications and ID123’s ID Management System.
