Volunteer Application Webhook Setup

The Volunteer Application webhook API is designed to accept a server-to-server HTTP POST from your main public website's server to the MOW Scheduler server, triggered by the submission of a volunteer application form on your public site. If you use a content management system such as WordPress on your public site, there is probably an available webhook plugin for this purpose.

HTTP Request

From our end, the submission looks very much like a submission direct from the user's browser (as described in the Simple POST setup guide), with a few minor differences:
  • the Comments spam trap field is not required, since hopefully you reject spam in your form handler before forwarding the data to us!
  • you should set the form variable API_Mode=1 -- this tells us to return a JSON response rather than human-readable HTML
  • Test_Mode is not currently used for webhook integration
  • the Thank_You_URL form variable is not applicable

Your request should contain the following elements

  • HTTP POST to https://<yoursite>.mowscheduler.com/api/webhooks/v1/volunteerapplication -- note that this is the same endpoint url used for the Simple POST
  • Content-Type: application/x-www-form-urlencoded -- we may support JSON POST in the near future, let us know if you're interesting in that.
  • Authentication: you must include your API_Key as a field. Get the value from the System Admin > Volunteer Application Form page in your MOW Scheduler install.
  • API_Mode: set the API_Mode field to 1 to indicate that this is a webhook submission, our system will return computer-friendly JSON response rather than human-readable HTML.
  • Field definitions: The volunteer application data submitted to MOW Scheduler must use our standard field names to allow us to automatically place the data in the correct fields in our Contact database. Only the First_Name and Email fields are required, all others are optional. You may also include custom fields that are not on our standard fields list by prefacing the field name with "X-", e.g. "X-Tee-Shirt_Size". These fields will be retained in the Volunteer Application attachment to the Contact record. There are also a few "meta-data" fields that help with the form submission process but are not part of the volunteer's application data, such as the API_Key field mentioned above. The required and optional standard and meta-data fields are listed in the Volunteer Application Field Reference

HTTP Response

The HTTP response to your POST will have Content-Type: application/json and contain a JSON string in the body.

success

The response JSON will look like this: { success: "1", contact_id: "234" } where the contact_id is the key for the newly created Contact record in MOW Scheduler. It can be used to construct a URL to the Contact profile, e.g. https://<yoursite>.mowscheduler.com/contacts/contact/234

failure

The response JSON will look like this: { success: "0", messages: ["Required field 'First_Name' missing."] } where the messages array may contain more than one message string.

Example Transaction

we can use the popular Curl command line client to simulate a complete webhook transaction. Here we receive a "success" response that indicates we created new Contact with contact_id 630 
> curl -v -H "Content-Type: application/x-www-form-urlencoded"
 -d "API_Key=XXXX-XXXX-XXXX-XXXX&First_Name=Joe&Last_Name=Berry&X-areapreference=east%20side&Email=jberry@gnail.com&API_Mode=1"
  https://mysite.mowscheduler.com/api/webhooks/v1/volunteerapplication
* About to connect() to mysite.mowscheduler.com port 443 (#0)
*   Trying 97.107.xxx.xxx...
* Connected to mysite.mowscheduler.com (97.107.xxx.xxx) port 443 (#0)
* [...]
> POST /api/webhooks/v1/volunteerapplication HTTP/1.1
> User-Agent: curl/7.29.0
> Host: mysite.mowscheduler.com
> Accept: */*
> Content-Type: application/x-www-form-urlencoded
> Content-Length: 121
>
* upload completely sent off: 121 out of 121 bytes
< HTTP/1.1 200 OK
< Date: Mon, 29 Jul 2019 14:29:17 GMT
< Server: Mojolicious (Perl)
< Content-Type: application/json; charset=utf-8
< Content-Length: 30
<
* Connection #0 to host mysite.mowscheduler.com left intact
{"contact_id":630,"success":1}%