5/10/2015 - 7:23 AM

Receive payloads from POST hooks with eXist

Receive payloads from POST hooks with eXist

xquery version "3.1";

Receive payloads from POST hooks with eXist


1. A post-January 2015 build of the develop branch of eXist, which adds support 
for XQuery 3.1's JSON parsing and serialization features. 

a) Check out and `` from:
b) Or install a nightly from 
(these seem to have stopped in February, but that should still do.)

2. A BitBucket account and repository.


1. Save this script as /db/apps/bbxq/payload.xq in your eXist database. Set 
execute permissions on the script to world-executable, because BitBucket will 
need to call this service via HTTP POST request.  (Assuming you're using eXide,
do this via File > Manager, select payload.xq, select the "i" (info) icon, 
and check all of the "execute" checkboxes. Then select the Apply button, then 
the Close button.)

Now the script should be accessible in your browser via:


You should see this message:

  <response status="fail">
    <message>No post data received</message>

This is to be expected.

2. Open monex to view the console logging output


Reload payload.xq in the browser, and you should see some logging of your 
request's headers and the the same <response> as before in the console window.
3. You need a public URL for your eXist server. If you don't have one, install
ngrok from This gives you a publicly reachable domain name, 
that tunnels to your computer on a port you determine. The ngrok command for 
opening port 8080 is

  ngrok http 8080

This command then displays the URL that ngrok has assigned you. Now pull up 
payload.xq via this URL:

Confirm that you see the same results as in steps 1 and 2 above.

4. Configure a POST hook on your BitBucket repository, using these directions:

When prompted for the URL where Bitbucket should send its update messages,
enter the publicly reachable URL for your payload.xq.

5. Push a commit to your repository. You should see the following console logs:

  <response status="success">
    <message>Payload received from</message>

    "repository": {
        "website": "",
        "fork": false,
        "name": "test",
        "scm": "git",
        "owner": "joewiz",
        "absolute_url": "/joewiz/test/",
        "slug": "test",
        "is_private": true
    "truncated": false,
    "commits": [{
        "node": "fb2a7271e09a",
        "files": [{
            "type": "modified",
            "file": ""
        "raw_author": "Joe Wicentowski <>",
        "utctimestamp": "2015-05-10 04:17:18+00:00",
        "author": "joewiz",
        "timestamp": "2015-05-10 06:17:18",
        "raw_node": "fb2a7271e09a4e393213c770330daf3d648423a1",
        "parents": ["f809e677d8e7"],
        "branch": "master",
        "message": " edited online with Bitbucket",
        "revision": null,
        "size": -1
    "canon_url": "",
    "user": "joewiz"

6. That's it! With this info, you can then use BitBucket's REST API to fetch
the changed files.


import module namespace console="";

declare namespace output = "";

let $post-data := request:get-data()
let $log := console:log(string-join(request:get-header-names() ! concat(., ': ', request:get-header(.)), '  --  ')) 
let $json-serialization-parameters := 
let $response-and-data := 
    if (not(empty($post-data))) then
        if (request:get-header('Content-Type') = 'application/x-www-form-urlencoded') then
            if (request:get-parameter-names() = 'payload') then
                try {
                    let $payload := request:get-parameter('payload', '')
                    let $json-data := parse-json($payload)
                        if (starts-with(request:get-header('User-Agent'), '')) then
                            <response status="success">
                                <message>Payload received from</message>
                            serialize($json-data, $json-serialization-parameters)
                            <response status="fail">
                                <message>Bitbucket User-Agent check failed: {request:get-header('User-Agent')}.</message>
                } catch * {
                    <response status="fail">
                        <message>There was an unexpected problem. {concat($err:code, ": ", $err:description, ' (', $err:module, ' ', $err:line-number, ':', $err:column-number, ')')}</message>
                <response status="fail">
                    <message>Expected a POST Parameter named 'payload', but only received '{string-join(request:get-parameter-names(), ', ')}'.</message>
            <response status="fail">
                <message>Expected a Content-Type header of 'application/x-www-form-urlencoded', but received '{request:get-header('Content-Type')}'.</message>
        <response status="fail">
            <message>No post data received</message>