Hello, there is a new feature allowing you to set callback URL’s (webhooks) for various background processing events.
For example, let’s assume you are post processing all your campaigns and you wanted to be notified of events that transpire when campaign and it’s transactions are being processed so that you could do some other post processing using such events within your own system.
Well you could accomplish that by first navigating to Administration Panel -> Webhooks -> Background Processor.
There (as depicted in screenshot below) you will see several URL’s that can be set for each type of events you want to listen for. Once set the processor will send the URL notifications automatically when there is new data available to process.
Event notification endpoints for Background Processor
- Process Ending Campaigns ( Endpoint URL for campaigns in ended state )
- Process Pre-Auth Campaigns ( Endpoint URL for campaigns in pre-auth state )
- Process Accepted For Capture Campaigns ( Endpoint URL for campaigns in accepted for capture state )
- Process Capture Campaigns ( Endpoint URL for campaigns in capture state )
- Process Cancelled Campaigns ( Endpoint URL for campaigns in cancelled state )
As campaigns transition through these event states appropriate callback URL’s will be invoked as set in the Administration Panel -> Webhooks -> Background Processor and your code can then execute to do something else.
The Callback URL will get JSON posted data with following main array keys.
“data” => Main Result Data
“error” => Any Processing Errors
“action” => Endpoint Action
“fingerprint” => Fingerprint or signature for the request so it can be verified
If you need to verify that requests are originating from your instance and not somewhere else then you can use fingerprint field. Simply take the fingerprint field which will come in the JSON callback request and send GET request as in the following example:
https://www.yourwebsite.com/api/service/restv1/portal/webhook-fingerprint/<Your Fingerprint ID>
You can also update fingerprint by sending PUT request to the same endpoint with fingerprint and used parameter set to true or false. This marks fingerprint as used. Note that signed fingerprints auto expire after 3 weeks from when they are created. Once expired they are removed from system.
Endpoint event actions are outlined further as per below.
| Action Name | Action Description | Endpoint |
| process_ending_direct | Campaign finalized as direct charge detected | #1 |
| process_ending_preauth | Campaign updated to pre-auth state, post processing detected | #1 |
| process_preauth_campaign | State change on campaign | #2 |
| process_preauth_transaction | Pre-auth performed on transaction | #2 |
| process_accepted_capture_campaign | State change on campaign | #3 |
| process_capture_campaign | State change on campaign | #4 |
| process_capture_transaction | Capture performed on transaction | #4 |
| process_cancelled_campaign | State change on campaign | #5 |
Event notification endpoints for Campaign
- Pledge Operations ( Endpoint URL for campaign pledges )
| Action Name | Action Description | Endpoint |
| pledge_create | Create campaign pledge | #1 |
| pledge_update | Update campaign pledge | #1 |
| pledge_delete | Delete campaign pledge | #1 |
NOTE: All event actions will result in either sucess or failure as indicated by the “error” structure returned. Also consider using HTTPS callback URL’s for increased security as information will be transmitted in encrypted form.
Below is example PHP code which can be used to listen for events on your side. You can however write such code in pretty much any modern language such as Python or Ruby.
date_default_timezone_set('America/Los_Angeles');
$current_date = date('m/d/Y h:i:s a', time());
$logfile = fopen('./notification.log', 'a');
fwrite( $logfile, "started callback handler at: $current_date\n" );
$text = file_get_contents('php://input')."\n";
$body = json_decode($text);
$results = print_r($body, true);
fwrite( $logfile, "raw dump is: $results\n" );