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 these user_traits as known facts about the user. By default, this is where user email and registration date would be located. Information such as user_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.