diff --git a/README.md b/README.md
index e1a478e..92a1e44 100644
--- a/README.md
+++ b/README.md
@@ -89,30 +89,20 @@ curl -d '{"body":"new contrib from toto: [44](http://radio.localhost/map/#44)",
 ```
 (or localhost:4785 without docker)
 
-### For Github
+### Formatters
 
-Add a JSON webhook with `?formatter=github`, and put the `API_KEY` as secret
-
-### For Grafana
-
-Add a webhook with a URL ending with `?formatter=grafana&key=API_KEY`
-
-### For Pingdom
-
-Add a webhook with a URL ending with `?formatter=pingdom&key=API_KEY`
-
-### For Buildgot
-
-Add a webhook with a URL ending with `?formatter=buildbot&key=API_KEY`
-
-### Generic formatter For anything that doesn't match specifically
-
-This is most useful when developing a plugin.  It will simply return the raw
-json of whatever was sent.  You *could* use this as a formatter, but it would
-look pretty ugly.
-
-Add a webhook with a URL ending with `?formatter=generic&key=API_KEY`
+These formatters will output custom messages depending on the specific formatter.  Generally to set these up, on the remote provider you would create a webhook with `https://your.webhook.domain/?formatter=<formatter columun below>&api_key=<your apikey>`
 
+| formatter | description | key location |
+| - | - | - |
+| github | for github.com | in github JSON webhook settings as `secret` |
+| grafana | for grafana | in URL with api_key=<yourkey> |
+| pingdom | for pingdom.com | in webhook URL with api_key=<yourkey> |
+| buildbot | buildbot reporter | in webhook URL with api_key=<yourkey> or in master.cfg credentials header as `api_key` |
+| generic | returns raw JSON that was recieved.  For developing additional formatter plugins | in URL with api_key=<yourkey> |
+  
+For example, if your matrix-webhook was hosted at https://webhooks.example.com, and you were setting up pingdom and you have an api_key of "123", you would use the following URL for your webhook call from pingdom:
+`https://webhooks.example.com/?formatter=pingdom&api_key=123`
 
 ## Test room