diff --git a/IPython/core/callbacks.py b/IPython/core/callbacks.py
index 4f6711c..9d2e509 100644
--- a/IPython/core/callbacks.py
+++ b/IPython/core/callbacks.py
@@ -120,5 +120,10 @@ def shell_initialised(ip):
     
     This is before extensions and startup scripts are loaded, so it can only be
     set by subclassing.
+    
+    Parameters
+    ----------
+    ip : :class:`~IPython.core.interactiveshell.InteractiveShell`
+      The newly initialised shell.
     """
     pass
diff --git a/docs/source/config/callbacks.rst b/docs/source/config/callbacks.rst
new file mode 100644
index 0000000..4a4e15c
--- /dev/null
+++ b/docs/source/config/callbacks.rst
@@ -0,0 +1,38 @@
+=====================
+Registering callbacks
+=====================
+
+Extension code can register callbacks functions which will be called on specific
+events within the IPython code. You can see the current list of available
+callbacks, and the parameters that will be passed with each, in the callback
+prototype functions defined in :mod:`IPython.core.callbacks`.
+
+To register callbacks, use :meth:`IPython.core.callbacks.CallbackManager.register`.
+For example::
+
+    class VarWatcher(object):
+        def __init__(self, ip):
+            self.shell = ip
+            self.last_x = None
+        
+        def pre_execute(self):
+            self.last_x = self.shell.user_ns.get('x', None)
+        
+        def post_execute(self):
+            if self.shell.user_ns.get('x', None) != self.last_x:
+                print("x changed!")
+
+    def load_ipython_extension(ip):
+        vw = VarWatcher(ip)
+        ip.callbacks.register('pre_execute', vw.pre_execute)
+        ip.callbacks.register('post_execute', vw.post_execute)
+
+.. seealso::
+
+   Module :mod:`IPython.core.hooks`
+     The older 'hooks' system allows end users to customise some parts of
+     IPython's behaviour.
+   
+   :doc:`inputtransforms`
+     By registering input transformers that don't change code, you can monitor
+     what is being executed.
diff --git a/docs/source/config/index.rst b/docs/source/config/index.rst
index 46fa2d9..c0fd3de 100644
--- a/docs/source/config/index.rst
+++ b/docs/source/config/index.rst
@@ -28,3 +28,4 @@ Extending and integrating with IPython
    extensions/index
    integrating
    inputtransforms
+   callbacks
diff --git a/docs/source/whatsnew/pr/callbacks.rst b/docs/source/whatsnew/pr/callbacks.rst
new file mode 100644
index 0000000..405d251
--- /dev/null
+++ b/docs/source/whatsnew/pr/callbacks.rst
@@ -0,0 +1 @@
+* A new callback system has been introduced. For details, see :doc:`/config/callbacks`.