Both sides previous revisionPrevious revisionNext revision | Previous revisionNext revisionBoth sides next revision |
v:2.0:webhooks [2019/11/06 05:29] – external edit 127.0.0.1 | 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 HTTP response code of ''200'', or in the case of the Legacy XML Webhook a response body of just ''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 === |
| |
| <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 === |
| |
^ 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. | |
</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 ====== |