Both sides previous revisionPrevious revisionNext revision | Previous revisionNext revisionBoth sides next revision |
v:2.0:webhooks [2019/11/05 13:48] – [Sending Webhooks & Automatic Retries] marija | v:2.0:webhooks [2020/02/25 06:13] – [Webhook Events] adam |
---|
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]] |
===== 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 ===== |
: 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. |
=== 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 === |
| |
| <note important>This currently relies on beta functionality that is manually enabled on a per store basis.</note> |
| |
| 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 === |
| |
^ 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. | |
==== 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. |
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 |
} | } |
} | } |
| |
} else { | } else { |
// JSON data not found | // JSON data not found |
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 |
| |
parsedData = JSON.parse(data) | parsedData = JSON.parse(data) |
| |
# Handle the payload | # Handle the payload |
puts parsedData['id'] | puts parsedData['id'] |
</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 ====== |