Documentation You are here: start » v » 2.0 » webhooks

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
Next revisionBoth sides next revision
v:2.0:webhooks [2019/11/05 13:48] – [Sending Webhooks & Automatic Retries] marijav:2.0:webhooks [2020/02/25 06:13] – [Webhook Events] adam
Line 7: Line 7:
 We currently have four different types of Webhook endpoints you can utilise, depending on your needs: We currently have four different types of Webhook endpoints you can utilise, depending on your needs:
   * [[#json_webhook|JSON Webhook]]   * [[#json_webhook|JSON Webhook]]
-  * [[#legacy_xml_webhook|Legacy XML Webhook]] 
   * [[#zapier|Zapier]]   * [[#zapier|Zapier]]
   * [[#webflow|Webflow]]   * [[#webflow|Webflow]]
Line 14: Line 13:
 ===== Sending Webhooks & Automatic Retries ===== ===== Sending Webhooks & Automatic Retries =====
  
-When a new transaction is placed and your webhooks are triggered, Foxy will wait for 1 minute for a response from your webhook endpoint. If a webhook fails to respond successfully (that is, if we don't receive a //200// HTTP Response Code, or in the case of the Legacy XML Webhook, //foxy//) in that time for any reason, Foxy will automatically reattempt to connect to your endpoint 11 more times within the following hour after it was initially attempted. The retries will get progressively further apart over the hour: ranging from around 1 minute apart up to around 10 minutes apart. If any of the retries are successful, no further attempts will be made.+When a new transaction is placed and your webhooks are triggered, Foxy will wait for 1 minute for a response from your webhook endpoint. If a webhook fails to respond successfully (that is, if we don't receive a HTTP response code of ''200'') in that time for any reason, Foxy will automatically reattempt to connect to your endpoint 11 more times within the following hour after it was initially attempted. The retries will get progressively further apart over the hour: ranging from around 1 minute apart up to around 10 minutes apart. If any of the retries are successful, no further attempts will be made.
  
 ===== PayPal, Amazon Pay, and other Hosted Gateways ===== ===== PayPal, Amazon Pay, and other Hosted Gateways =====
Line 61: Line 60:
   : The title of the webhook   : The title of the webhook
   ; ''TYPE''   ; ''TYPE''
-  : The type of webhook - ''json'', ''legacy_xml'', ''zapier'', ''webflow''.+  : The type of webhook - ''json'', ''zapier'', ''webflow''.
   ; ''ERROR_MESSAGE''   ; ''ERROR_MESSAGE''
   : The error message received from the endpoint, trimmed to 500 characters. For the JSON Webhook this is the body of the response.   : The error message received from the endpoint, trimmed to 500 characters. For the JSON Webhook this is the body of the response.
Line 109: Line 108:
 === Transaction Created === === Transaction Created ===
 The Transaction Created webhook option receives any transaction for the store, whether it's a new transaction, a subscription renewal, an update of customer info, or a customer-initiated subscription cancel (technically, when a subscription end date is set – always a future date). Those all generate a transaction in the system, so are fed to the endpoint. The Transaction Created webhook option receives any transaction for the store, whether it's a new transaction, a subscription renewal, an update of customer info, or a customer-initiated subscription cancel (technically, when a subscription end date is set – always a future date). Those all generate a transaction in the system, so are fed to the endpoint.
 +
 +=== Transaction Captured/Refunded/Voided ===
 +
 +<wrap hi>This currently relies on beta functionality that is manually enabled on a per store basis.</wrap>
 +
 +The three events for Captured, Refunded and Voided occur when a transaction is either captured, refunded or voided. This can be triggered either through the transaction report section of the Foxy administration, or through [[https://api.foxycart.com|the API]]. Note that the Captured event here is for a previously uncaptured transaction that was either verified or authorized that is then manually captured. For a transaction that is captured at the time of processing is considered a Transaction Completed event.
  
 === Subscription Cancelled === === Subscription Cancelled ===
Line 128: Line 133:
  
 ^ Header ^ Description ^ ^ Header ^ Description ^
-| ''Foxy-Webhook-Event'' | Name of the event that triggered this payload. Currently ''transaction/created'' and ''subscription/cancelled''. |+| ''Foxy-Webhook-Event'' | Name of the event that triggered this payload. Currently ''transaction/created'', ''transaction/captured'', ''transaction/refunded'', ''transaction/voided'', ''subscription/cancelled''. |
 | ''Foxy-Webhook-Signature'' | A HMAC SHA256 signature of the payload, using the webhook's encryption key. Used for verifying the contents of the payload. | | ''Foxy-Webhook-Signature'' | A HMAC SHA256 signature of the payload, using the webhook's encryption key. Used for verifying the contents of the payload. |
 | ''Foxy-Webhook-Refeed'' | A boolean to signify if this payload has been refed. If ''false'', then this is the first time this specific instance of the event has been triggered. | | ''Foxy-Webhook-Refeed'' | A boolean to signify if this payload has been refed. If ''false'', then this is the first time this specific instance of the event has been triggered. |
Line 136: Line 141:
 ==== Example Payload ==== ==== Example Payload ====
  
-The JSON payload will follow much the same structure as our Hypermedia API. Most of the objects will include the API's ''_links'' array. These contain helpful URI's that could be used to access the specific resources in the API if you're also making use of that. If not, these can be safely ignored. +The JSON payload will follow much the same structure as our Hypermedia API. Most of the objects will include the API's ''_links'' array. These contain helpful URI's that could be used to access the specific resources in the API if you're also making use of that. If not, these can be safely ignored.
  
 The source of the payload data is our Hypermedia API, so you can use [[https://api.foxycart.com/docs/reference|the documentation]] for the different resources for further information on the data it contains. The source of the payload data is our Hypermedia API, so you can use [[https://api.foxycart.com/docs/reference|the documentation]] for the different resources for further information on the data it contains.
Line 657: Line 662:
 if (is_array($parsedData)) { if (is_array($parsedData)) {
     // Handle the payload     // Handle the payload
-    +
     if ($event == "transaction/created") {     if ($event == "transaction/created") {
         // The following is an example of working with the transaction/created payload         // The following is an example of working with the transaction/created payload
Line 685: Line 690:
         }         }
     }     }
-    +
 } else { } else {
     // JSON data not found     // JSON data not found
Line 706: Line 711:
     return halt 500, "Signature verification failed - data corrupted" unless Rack::Utils.secure_compare(signature, request.env['HTTP_FOXY_WEBHOOK_SIGNATURE'])     return halt 500, "Signature verification failed - data corrupted" unless Rack::Utils.secure_compare(signature, request.env['HTTP_FOXY_WEBHOOK_SIGNATURE'])
 end end
- +
 post '/webhook' do post '/webhook' do
     request.body.rewind     request.body.rewind
Line 714: Line 719:
  
     parsedData = JSON.parse(data)     parsedData = JSON.parse(data)
-    +
     # Handle the payload     # Handle the payload
     puts parsedData['id']     puts parsedData['id']
Line 794: Line 799:
 </code> </code>
  
-====== Legacy XML Webhook ====== 
- 
-The Legacy XML Webhook matches our previous XML datafeed functionality, and shouldn't be used for any brand new integrations - but can be useful for connecting to existing endpoints/integrations which were built against our datafeed functionality. For details on how to accept and process the XML payload, you can review [[.:transaction_xml_datafeed|the existing documentation here]]. 
- 
-The only new functionality that the Webhooks version introduces beyond the documentation linked above is the ability to specify multiple endpoints from the "Integrations" section of the FoxyCart administration, and the automatic retries after failures. The API key used to decrypt the datafeed is still the key detailed on the "Advanced" settings page in the administration. 
  
 ====== Zapier ====== ====== Zapier ======

Page Tools

Site Tools