Skip to content

All hooks

This is an overview list of all available hooks and the event listeners that are supported for use outside of core. Any event listeners not listed here are not supported for use outside of core & could change without notice

Batch Hooks

Case Hooks

Database Hooks

Dedupe Hooks

  • hook_civicrm_findDuplicates - called when contacts are added/updated via profiles, event registration pages, contribution pages etc. When a form is submitted CiviCRM checks if a contact already exists using one of the built-in deduplication rules and returns a contact ID if a match is found. allows you to override the contact matching rules to implement more complex rules.

Entity Hooks

  • hook_civicrm_entityTypes - Lowest-level hook for modifying the list of system entities.
  • civi.entity.fields - This Symfony event is dispatched when retrieving metadata fields for a given entity. It replaces the deprecated fields_callback callback. Developers can listen to this event generally, or target a specific entity using the event name format civi.entity.fields::[EntityName] (e.g. civi.entity.fields::Activity).

Extension Lifecycle Hooks

Form Hooks

FormBuilder Hooks

  • civi.afform.get - This Symfony event allows developers to register or modify Afforms programmatically. It is dispatched during the Afform APIv4 get action.
  • civi.afform.prefill - This Symfony event is dispatched when prefilling an Afform (Angular Form) with default/existing data. It allows developers to customize or override the IDs used to load default values for entities and join relationships on the form.
  • civi.afform.validate - This Symfony event is dispatched during Afform submission validation. It allows developers to perform custom validation checks and add errors to prevent form submission.
  • civi.afform.submit - This Symfony event is dispatched during Afform submission processing. It handles the saving of individual form entities. Developers can use this event to customize records before they are saved, perform custom save logic, or intercept submission actions.
  • civi.afform_admin.metadata - This Symfony event is dispatched to alter metadata for the FormBuilder GUI. It allows developers to add or customize entities, elements, styles, permissions, input types, and submission tokens in the editor interface.

GUI Hooks

  • hook_civicrm_activeTheme - The activeTheme hook determines which theme is active.
  • hook_civicrm_alterBundle - Specify the content of a resource bundle (JS/CSS/etc).
  • hook_civicrm_alterCustomFieldDisplayValue - allows modification of custom field value for an entity eg Individual, Contribution etc before its displayed on screen. This might be useful if you want to alter the value of the custom field that's being displayed on the screen based on some condition.
  • hook_civicrm_alterEntityRefParams - called when an entityRef field is rendered in a form, which allows you to modify the parameters used to fetch options for this kind of field.
  • hook_civicrm_alterMenu - called when building CiviCRM's list of HTTP routes and should be used when you want to register custom paths or URLS.
  • hook_civicrm_alterAdminPanel - invoked after all the panels and items on Administer CiviCRM screen have been generated and allows for direct manipulation of these items and panels.
  • hook_civicrm_buildAmount - called when building the amount structure for a Contribution or Event Page, allowing you to modify the set of radio buttons representing amounts for contribution levels and event registration fees.
  • hook_civicrm_caseSummary - called when the manage case screen is displayed, and it allows the injection of label/value pairs which are rendered inside divs underneath the existing summary table.
  • hook_civicrm_contact_get_displayname - called when retrieving the display name of a contact, allowing you to alter it and return a custom display name.
  • hook_civicrm_dashboard - called when rendering the dashboard page and can be used to add content to the dashboard page.
  • hook_civicrm_dashboard_defaults - called while a contact views their dashboard for the first time and can be used to enable or disable the set of default dashlets.
  • hook_civicrm_fieldOptions - Dynamically modify the option list for any field (including custom fields).
  • hook_civicrm_links - Programmatically alter a list of links. called from various screens that display lists of links, including: - Action links at the end of a search result row - Action links on a tabular admin screen - Action links on a tabular contact summary tab - The "Create New" dropdown - The Actions dropdown at the top of a contact record.
  • hook_civicrm_navigationMenu - called after the menus are rebuilt.
  • hook_civicrm_pageRun - called before a CiviCRM page is rendered.
  • hook_civicrm_searchColumns - called after a search is done, allowing you to modify the headers and/or the values that are displayed as part of the search.
  • hook_civicrm_searchTasks - called to display the list of actions allowed after doing a search, allowing you to inject additional actions or to remove existing actions to legacy style searches. For SearchKit searches use hook_civicrm_searchKitTasks.
  • hook_civicrm_searchKitTasks - called to allow you to add to or alter the tasks available in search kit.
  • hook_civicrm_summary - called when the contact summary is rendered, allowing you to modify the summary with your own content.
  • hook_civicrm_summaryActions - allows you to customize the context menu actions on the Contact Summary Page.
  • hook_civicrm_themes - called when building a list of available themes for use within CiviCRM.
  • hook_civicrm_tabset - called when composing the tabs interface used for contacts, contributions and events.
  • hook_civicrm_xmlMenu - called when building CiviCRM's menu structure, which is used to render urls in CiviCRM.

Import Hooks

  • hook_civicrm_importAlterMappedRow - allows an import row to be adjusted, after the user configuration has been interpreted into an apiv4-ready format. It is called twice. The first time the usage is validate and the second time the usage is import. In the validate usage you should avoid doing any db lookups or anything resource intensive. Validate mode is intended for a quick pass before presenting the preview screen. For the import usage you can do more intensive lookups and change the data if needed.

Mail Hooks

Membership Hooks

Permission Hooks

  • hook_civicrm_aclGroup - called when composing the ACL to restrict access to civicrm entities (civicrm groups, profiles and events).
  • hook_civicrm_aclWhereClause - called when composing the ACL where clause to restrict visibility of contacts to the logged in user.
  • hook_civicrm_alterApiRoutePermissions - called when API version 4 permissions are checked. Note that this does not apply to API version 3.
  • civi.api4.authorizeRecord - This Symfony event determines if the current user has write access to a given record. It is dispatched when checking permissions for write operations (create, update, delete) in APIv4. It does not affect read access for get actions.
  • hook_civicrm_invalidateChecksum - allows you to invalidate contact checksums (see https://docs.civicrm.org/user/en/latest/common-workflows/tokens-and-mail-merge/#checksum). It does NOT allow marking a checksum as valid because it could easily open up a security hole - e.g. it could inadvertently allow access to data it shouldn't, especially if multiple extensions implement the hook.
  • hook_civicrm_permission - Allow custom permissions to be defined. These will appear along with core permissions in the UI and can be granted to user roles. They can be checked using CRM_Core_Permission::check().
  • hook_civicrm_permission_check - called to dynamically alter permissions based on conditions or external criteria.
  • hook_civicrm_permissionList - enumerates special or external permissions, making them available for use in CiviCRM configuration.
  • hook_civicrm_selectWhereClause - allows the permission (ACL) clause of a SELECT query to be altered. It is called for all API-based queries (e.g. SearchKit) but not all legacy queries (e.g. search, report).

Profile Hooks

Queue Hooks

  • hook_civicrm_queueActive - Hook to inform background queue processor not to process items. called when a background process attempts to claim an item from the queue to process. A hook could alter the status from 'active' to denote that the server is busy & hence no item should be claimed and processed at this time.
  • hook_civicrm_queueRun - Fire hook_civicrm_queueRun_{$runner}.
  • hook_civicrm_queueStatus - # hook_civicrm_QueueStatus.
  • hook_civicrm_queueTaskError - allows for the modification of how a queue task Error is handled.

Report Hooks

  • hook_civicrm_alterReportVar - used to add or modify display columns and filters. The hooks does not have a well defined contract but CiviReport is not really being developed anymore so it is fairly static. can be used for light modification of CiviReports but in general is is more robust to create your own report template or to use SearchKit instead. In general the CiviReport framework is expected to be replaced by SearchKit As always you should ensure your code has good test cover to avoid breakage on upgrade - especially if you are using getVar() or setVar() to access the internals of the report object.

SMS Hooks

  • hook_civicrm_inboundSMS - called when an inbound SMS has been received, processed by the provider extension, but not matched or processed by CiviSMS.

Scheduled Job / cron Hooks

Token Hooks/listeners

  • civi.token.eval - This event is dispatched when evaluating tokens.
  • civi.token.list - This event is dispatched when listing/registering tokens.
  • civi.token.render - This Symfony event is dispatched after a message template has been rendered and all tokens replaced. It allows developers to perform post-processing or cleanup on the rendered output string.

Uncategorized Hooks

  • hook_civicrm_alterBadge - allows you to modify the content and format of name badges.
  • hook_civicrm_alterBarcode - allows you to modify the content that is encoded in barcode.
  • hook_civicrm_alterExternUrl - allows you to modify extern urls such as click tracking, tracked opens urls.
  • hook_civicrm_alterLogTables - allows you to amend the specification of the log tables to be created when logging is turned on.
  • hook_civicrm_alterMailingLabelParams - called to alter the parameters used to generate mailing labels.
  • hook_civicrm_alterPaymentProcessorParams - allows you to modify parameters passed to the payment processor.
  • hook_civicrm_alterRedirect - called when when the browser is being redirected. This allows extensions to override the destination of an HTTP redirect.
  • hook_civicrm_alterSettingsFolders - allows modules and extensions to scan for settings in additional folders.
  • hook_civicrm_alterSettingsMetaData - called when Settings have been loaded from the xml. It is an opportunity for hooks to alter the data.
  • hook_civicrm_alterUFFIelds - allows for the modification of the available fields that are permissible for use within a profile. This might be useful for when you have an extension that has defined it's own entities or it is seeking to permit a core component that doesn't show up in profiles by default e.g. Grants.
  • hook_civicrm_angularModules - generates a list of AngularJS modules and allows you to register additional AngularJS modules. Extensions generated with civix implement this hook by default to automatically scan the extension's ang directory for files ending in .ang.php.
  • hook_civicrm_apiWrappers - allows you to add, override, or remove methods to be called before and after API calls — and to modify either the parameters or the result of the call.
  • hook_civicrm_buildAsset - fires whenever the system builds a semi-dynamic asset.
  • hook_civicrm_buildStateProvinceForCountry - called during the ajax callback that is used to build the options that display in the State/Province select widget for a specific country, and can be used to alter the list of State/Province options for particular countries.
  • hook_civicrm_check - called by the "System Check" api.
  • hook_civicrm_config - called soon after the CRM_Core_Config object has been initialized.
  • hook_civicrm_container - modifies the CiviCRM container allowing you to add new services, parameters, extensions, etc.
  • hook_civicrm_crypto - added in 5.33 and allows for extension authors to define more keys and ciphers that are then used in the Crypto Registry.
  • hook_civicrm_cryptoRotateKey - When a system administrator changes the cryptographic key used for data-storage, this event fires. Listen to this event to re-encrypt data with the new key.
  • hook_civicrm_eventDiscount - allows you to apply a customized discount to an event registration.
  • hook_civicrm_export - allows to manipulate or change the output of CSV during export.
  • hook_civicrm_fileSearches - allows you to add a reference to a file search service (e.g. Solr).
  • hook_civicrm_geocoderFormat - allows you to manipulate the Address object during geocoding, for instance to extract additional fields from the geocoder's returned XML.
  • hook_civicrm_getAssetUrl - called when building a link to a semi-static asset, allowing you to modify the params the asset will be built with.
  • hook_civicrm_oauthProviders - generates a list of OAuth providers.
  • hook_civicrm_oauthReturn - After a user has approved an OAuth2 grant (in the "authorization code" flow), we may perform additional work.
  • hook_civicrm_oauthReturnError - If an OAuth2 grant (in the "authorization code" flow) produces an error, then this hook provides details.
  • hook_civicrm_postIPNProcess - allows you to do custom processing of IPN Data following CiviCRM processing.
  • hook_civicrm_queryObjects - called while building the core search query, allowing you to provide your own query objects which alter or extend the core search.
  • hook_civicrm_recent - called before storing recently viewed items.
  • hook_civicrm_relativeDate - Allows extensions to define custom relative date filters by returning an array with from and to date values, enabling flexible filtering beyond the built-in formats. If your filter is just adding a longer interval to an existing filter you may not need the hook. See Adding New Filters in the user guide.
  • hook_civicrm_scanClasses - Scan extensions for classes. This allows auto-registration based on code-conventions, interfaces, annotations.
  • hook_civicrm_unhandledException - fires when an unhandled exception (fatal error) occurs.
  • hook_civicrm_userContentPolicy - called when Smarty Security mode is enabled for user content evaluation such as in message templates.

Deprecated Hooks