Webhooks are messages sent by SIGNIFYD via HTTP POST to a url you configure on your Notifications page in the SIGNIFYD settings. They allow your application to receive pushed updates about an investigation, rather than poll SIGNIFYD for status changes.

Webhook Events

You can create webhooks in Signifyd for the following events. Each event has a corresponding topic identifier
which will be sent in the X-SIGNIFYD-TOPIC header of the webhook. Getting Started

Currently, the following events can trigger a webhook. Only one URL may be specified per event.

Responding to a Webhook

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

If your endpoint does not successfully receive a webhook we will resend the webhook up to 15 times over four days. The first webhook will be retried after 20s with expotential delays for each subsequent retry. Webhooks cannot be manually retriggered, however you can retrieve the status of a guarantee or case by making a GET request on the applicable resource.

Verifying a Webhook

To allow a client to verify a webhook message has in fact 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. To verify the authenticity of the webhook message, you should calculate this value yourself and verify it equals the value contained in the header.

Here's an example of how to compute the value in Java.

Mac sha256HMAC = javax.crypto.Mac.getInstance("HmacSHA256"); 
SecretKeySpec secretKey = new SecretKeySpec(teamAPIKEY.getBytes(), "HmacSHA256"); 
sha256HMAC.init(secretKey); 
String encodedHMAC256 = Base64.encodeBase64String(sha256HMAC.doFinal(jsonBody.getBytes("UTF-8")));

Testing a Webhook

Once a webhook is configured, a test POST can be sent by selecting the Test button next to the desired webhook in the Signifyd console settings.
The test webhook message is sent with an HMAC SHA256 verification header (see Webhook Verification below).
The header value is the Base64 encoded output of the HMAC SHA256 encoding of the test webhook JSON body,
using the team API key when available. The test webhook message uses the secret key ABCDE. A 'cases/test' topic header is also sent with the test POST.

Webhook Response

Decision Made

For field definition, please refer to the field definition of Get Case.

{
  “caseId”: 1,
  "customerCaseId": "19418"
  "createdAt":"2013-11-05T14:23:26-0800",
  "updatedAt":"2013-11-05T14:23:26-0800",
  “isTest”: true,
  “score“:262,
  “checkpointAction”: “ACCEPT”,
  "checkpointActionReason" : "MY_CUSTOMER_POLICY_A"
}

Cases and Guarantees

{
   "analysisUrl":"https://signifyd.com/v2/cases/1/analysis",
   "notesUrl":"https://signifyd.com/v2/cases/1/notes",
   "guaranteeEligible":false,
   "status":"DISMISSED",
   "uuid":"709b9107-eda0-4cdd-bdac-a82f51a8a3f3",
   "headline":"John Smith",
   "reviewDisposition":null,
   "associatedTeam":{
      "teamName":"anyTeam",
      "teamId":26,
      "getAutoDismiss":true,
      "getTeamDismissalDays":2
   },
   "orderId":"19418",
   "orderDate":"2013-06-17T06:20:47-0700",
   "orderAmount":365.99,
   "createdAt":"2013-11-05T14:23:26-0800",
   "updatedAt":"2013-11-05T14:23:26-0800",
   "investigationId":1,
   "score":262,
   "caseId":1,
   "guaranteeDisposition":"APPROVED"
}

Claim Reviewed

{
   "caseId":1,
   "orderId":"19418",
   "createdAt":"2016-02-21T06:45:05.343Z",
   "updatedAt":"2016-02-21T06:45:05.343Z",
   "amount":365.99,
   "currency":"USD",
   "status":"CLOSED",
   "disposition":"APPROVED",
   "dispositionReason":"elgible chargeback"
}

Claim Payouts

{
   "caseId":1,
   "orderId":"19418",
   "createdAt":"2016-02-21T06:45:05.343Z",
   "updatedAt":"2016-02-21T06:45:05.343Z",
   "amount":365.99,
   "currency":"USD",
   "status":"CLOSED",
   "disposition":"APPROVED",
   "dispositionReason":"elgible chargeback",
   "payouts":[
    {
      "id":123,
      "createdAt":"2016-08-18T06:17:10.225Z",
      "payoutDate":"2016-08-18",
      "method":"PayPal",
      "currency":"USD",
      "amount":101.95,
      "transactionId":"1232"
    }
  ]
}