How to Use Sift’s Asynchronous Webhook Notifications Securely

Sift Workflows and Decisions are powerful tools for automating more of your fraud review processes. We’ve gotten a lot of positive feedback from customers about how Workflows and Decisions are helping them streamline fraud management, as well as some questions about best practices. In this blog post, we’ll share guidelines for the best, most secure way to use Decisions Webhooks to automate tasks that need to be done asynchronously.

Why signing webhooks matters

A webhook endpoint is a public URL, and anyone who finds it can send it a request. Without a way to confirm the sender, a forged notification could trick your systems into releasing an order, unblocking an account, or ignoring a real fraud decision. Signing closes that gap. Sift attaches a signature, built from your signature key and the body of the notification, to every Decisions webhook, and your server recomputes it to confirm the message came from Sift and was not altered along the way.

As a very first step, you’ll need to set up some Decisions and create Workflows, which will apply those Decisions based on a set of rules that you define. You can read all about how to do that in our Configure Workflows Tutorial.

Already got Workflows and Decisions set up? Great! The next step is to set up Decisions Webhook Signing to validate that notifications are coming from us. Here’s how to get Decisions Webhook Signing running in a few easy steps:

Step 1: Before setting up Decisions Webhooks, you’ll want to enable webhook signing so that you can verify that the notifications are coming from Sift. To do so, go to the API Keys Tab of our developer page in the Sift console. There you’ll see a section called Signature Keys:

Step 2: Click on “New Signature Key”, choose encryption type (by default it will be SHA-256 as newer and more secure than SHA-1), and click “Create Key”: 

Step 3: Now you need to activate the newly created Key. Navigate mouse to hover the “Disabled” button.

You will see it turn into an “Enable” button instead. Click it to enable the new Signature Key.

Pay attention that only one key can be active at a time.

Your new signature key is active! You may only have one active key at a time. Make a note of it, because you’ll use it later in your code base.

Now that you’ve enabled webhook signing on Sift, all webhook notifications generated by our Workflows and Decisions will have a signature in the HTTP header under “X-Sift-Science-Signature”. This signature is calculated by generating an SHA-256 (or SHA-1 if you’ve chosen less secure encryption type) hash of your signature key and the body of the notification.

Step 4: In order to verify that an http notification is coming from Sift, create an SHA256 hash of your signature key combined with the body of the notification you received and compare it to the signature value in the HTTP header. It’s that easy! Here’s some sample code to give you an idea of how your webhook verification should operate:

For additional code examples, check out our webhook authentication documentation. Questions? Contact our support team.

Best practices for verifying signatures

Once verification works, a few habits keep it reliable:

• Verify the raw request body. Use the body exactly as received. Parsing and re-serializing JSON can change spacing or key order and break the match.
• Use a constant-time comparison. A standard string comparison can leak timing information, so use your language’s secure compare function.
• Reject first, process later. Discard any request with a missing or invalid signature before doing anything else, and log the attempt.
• Protect the key. Store it in a secrets manager or environment variable, never in source code.
• Serve your endpoint over HTTPS so notifications are encrypted in transit.
• Acknowledge quickly. Return a success response once the signature checks out, and hand heavier work to a background job so notifications are not delayed.
• Plan for key changes. Because only one key can be active at a time, update your code as soon as you enable a new key. Notifications signed with the new key will fail verification until you do.

Troubleshooting signature mismatches

If verification keeps failing, check these four things first:

• The key: Confirm your code uses the currently active signature key.
• The hash type: The key was created as SHA-256 or SHA-1, and your code needs to use the same one.
• The body: Hash the raw body byte for byte, without trimming whitespace or re-encoding it.
• The header: Read the signature from “X-Sift-Science-Signature” exactly as sent.

If it still fails, contact our support team with an example request.

Frequently asked questions