PHP version of the SKY Developer Webhooks Tutorial.
This code sample handles three scenarios:
- The
OPTIONrequest necessary to validate a subscription registration. - The
POSTrequest when real webhook events or the test payload are delivered. These requests are stored in a localhandler/results.jsonfile. - All other requests display the contents of the
handler/results.jsonfile. This is for debugging purposes only.
- Replace the value for
WEBHOOK_SECRET_KEYin theindex.phpwith a unique value for you. - Host this repo on the webserver of your choice with PHP support.
- Use your webserver host URL +
/handler/?key=[WEBHOOK_SECRET_KEY]when you register your webhook subscription. - Trigger a webhook event.
- Visit your webserver host URL +
/handler/to see any events that were delivered.
This code has been tested on a wide variety of hosts supporting PHP, including but not limited to the following:
- "Shared" hosting providers including HostGator and Eleven2.
- Local Apache instance setup with ModSecurity using vagrant.
- Azure, AWS, and Digital Ocean.
As a note, we recommend extreme caution using shared hosting providers for any serious production workloads.
Last, a stock installation of ModSecurity is known to block the content-type of application/cloudevents+json. This will typically result in a 403 or 406 HTTP error. Given the somewhat recent push for this schema, our current plan is to continue to require it.
Many hosting providers expose ModSecurity configuration options. While disabling completely is a possibility, we hope that to be an absolute last resort. We found that even those that do not expose configuration, their support staff were very accommodating in making changes.
On a personal note, this actually happened with us. The very knowledgeable support staff at HostGator understood our problem and very promptly whitelisted the content-type in about 5 minutes for their entire fleet.
Please do not hesitate to reach out via the Blackbaud Community with any questions you may have.