Skip to content

Configuring Webhooks

Overview

Signifyd can send a webhook to notify your online store every time a guarantee decision is made on a submitted order. This provides you with real-time updates enabling you to ship orders quickly and efficiently. Webhooks can also be used to notify other systems, like Order Management Systems (OMS), that are not directly responsible for making the API request, but still need to know the result of the guarantee decision.

This section of the guide will cover the following steps:

  1. Create Endpoint >
  2. Set Up Webhook Events >
  3. Parse Webhook >
  4. Automate Workflows >

Tip: We recommend the use of webhooks since they provide instant feedback when a decision is made on an order; however, you can use the Signifyd Get Case API to poll for the guarantee decision of the case.

Guarantee Statuses and Definitions

GUARANTEE STATUS

DESCRIPTION

WEBHOOK EVENT

Pending The case is waiting to be reviewed for fraud. This is the inital status of the case when submitted. None
In Review The case is being reviewed for fraud. None
Approved The case has been reviewed for fraud and is safe to ship. If the order results in a fraudulent chargeback it is eligible for reimbursement. Guarantee Completion
Declined The case has been reviewed for fraud and is not safe to ship. If the order results in a fraudulent chargeback it is not eligible for reimbursement. Guarantee Completion
Canceled The request to guarantee the order was canceled when the status was approved, pending, or in review. If the order results in a fraudulent chargeback it is not eligible for reimbursement. None
Unrequested The case has not been submitted for guarantee. If the order results in a fraudulent chargeback it is not eligible for reimbursement. None

1. Create Endpoint

You'll need to create a publicly accessible endpoint for Signifyd's webhook notifications toPOSTto.

Creating a webhook endpoint on your server is no different from creating any page on your website. You can use a framework like Sinatra or ngrok and add a new route with the desired URL.

2. Set Up Webhook Events

Once you have a publicly accessible webhook endpoint, you can add the webhook URL in Signifyd’s Developer Tools so that Signifyd can notify your system every time a guarantee decision is made on a submitted order.

  1. Go to Teams in Developer Tools.
  2. On the Teams page find the team you would like to configure webhooks for.
  3. Select Settings and then Webhooks.
  4. Enter the Webhook Address and select the event type of Guarantees/Reviewed.
  5. Click Add.

Tip: You can send a test notification to the endpoint by clicking the Test button. If there is an issue with posting to the endpoint, a message will be shown with the error.

Webhooks for each team can be set up via Settings in the Developer Tools web app.

Note: A webhook will not be sent if the guarantee decision is Pending, Canceled, or In Review.

3. Parse Webhook

Webhook data is sent as JSON in the POST request body. The JSON can be parsed into an Event object.

Parsing json to an event object

  1. $request = file_get_contents("php://input");
  2. $$eventJson = json_decode($request, true);
  3. $// Handle received event
  4. $http_response_code(200);

We recommend saving the following fields from the webhook body to your ecommerce platform.

  • caseID
  • guaranteeDisposition

Tip: You can verify if the webhook was sent by Signifyd by checking the signature in the header of the webhook message.

To verify a webhook message has come from SIGNIFYD, an X-SIGNIFYD-SEC-HMAC-SHA256 header is included in each webhook POST message. The contents of this header is the Base64 encoded output of the HMAC SHA256 encoding of the JSON body of the message, using the team's API key as the encryption key.

You should calculate this value and verify it matches the value contained in the header.

Webhook Verification Process

  1. $request = file_get_contents("php://input");
  2. // Signifyd webhook headers include - but PHP replaces them with _ on $_SERVER and adds 'HTTP_ before it
  3. $phpServerHeaderHash = 'HTTP_' . str_replace('-', '_', 'X-SIGNIFYD-SEC-HMAC-SHA256');
  4. $hash = $_SERVER[$phpServerHeaderHash];
  5. $check = base64_encode(hash_hmac('sha256', $request, $apiKey, true));
  6. $isValidRequest = $hash == $check ? true : false;

4. Automate Workflows

To automate order fulfillment you’ll want to take action in your online store or Order Management System (OMS) based on Signifyd’s guarantee decision. The specific actions that you may need take in your system to complete order fulfillment may vary, however, you should consider the following actions when defining your workflows.

Scenario 1: Ship Approved Orders

When Signifyd makes a guarantee decision of approved ship the order and capture the payment immediately.

  • Guarantee Decision: Approved
  • Order Status: Fulfilled
  • Payment Status: Captured
  • Buyer Communication: Your order is shipping

Scenario 2: Manually Review Orders that Are Declined.

The order is placed on hold so your team can review the order in the Signifyd console.

  • Guarantee Decision: Declined
  • Order Status: Hold
  • Payment Status: Authorized/Sale
  • Buyer Communication: None

 

You can then manually take the following actions:

  • Cancel: If your review team agrees with Signifyd and believes the order is fraudulent, cancel the order.
  • Resubmit: If your review team believes the order is not fraud, you can resubmit it for a second review.
  • Ship without a guarantee: If you choose, you can ship the order without guarantee fraud protection.

Scenario 3: Cancel orders that are declined.

Cancel the order and void/refund the payment immediately

  • Guarantee Decision: Declined
  • Order Status: Cancel
  • Payment Status: Void/Refund
  • Buyer Communication: Your order is canceled

Handling Errors

To acknowledge receipt of a webhook, your endpoint should be publicly accessible and return a 2xx HTTP status code. All response codes outside of this range, including 3xx codes, will indicate to Signifyd that you did not receive the webhook including URL redirection or "Not Modified" responses.

If your endpoint is down or not able to successfully receive a webhook Signifyd will resend the webhook up to 15 times over a four day period. The first webhook will be retried after 20 seconds with exponential delays for each subsequent retry.

RETRY

TIME

1 20s
2 40s
3 80s
4 160s
5 320s
6 640s

Wrap Up

Congratulations, you have completed your Signifyd integration!

Your Signifyd Implementation Manager will now guide you through the deploying your integration to your production store.

Was this page helpful?