API Custom Parameters
Adding custom data to Castle events
You may add custom user or event details to the payload of any of Castle's recognized events. These custom parameters are added as key-value pairs within the properties
or user_traits
objects in event payloads. The properties
and user_traits
objects provide slightly different ways to manage your custom parameters:
- Key-value pairs added to the
properties
object applies to the event to which they are attached. Use this for custom details that add context to the event. For instance, if you use the standard$profile_update.succeeded
event, you may include"event_type": "billing change"
or"update_type": "phone number"
, etc. For transaction events, you might include"transaction_type": "withdrawal"
or"transaction amount": 100
, etc. - Key-value pairs added to the
user_traits
object of an event are intended to apply to the user and will be persisted in Castle's copy of the user record. Think of theseuser_traits
as known facts about the user. By default, this is where user email and registration date would be located. Information such asuser_type
(admin, power-user, etc.) or any other relevant user/account information may also be added here
The example below shows where to insert custom user_traits
and properties

Your custom parameters will be visible in the event debugger and they’ll be returned within webhook payloads. You'll be able to define custom Risk Policies to take action on events tied to these properties as well.
NOTE: It is up to you to decide whether to include any personally identifiable information (PII) about your user in custom parameters sent to Castle. If you do include such information, please take note of Castle's privacy policy for protecting user information and our APIs for deleting such information on request. If you choose to include an email
key-value pair within user_traits
, we will use it to improve the quality of our predictions. You are also welcome to omit it or anonymize user IDs to reduce concerns about PII.
Updated over 1 year ago