Configure webhooks

{
  "created": "2023-10-05T17:38:26.698516-07:00",
  "data": {
    "ebt_cash_total": "10.00",
    "external_order_id": "58503b96-5111-495b-b13b-d9247be12e75",
    "merchant_fns": "121212",
    "merchant_id": "2fb3asd",
    "order_ref": "3ee466e0ef",
    "payments": [
      {
        "amount": "10.00",
        "funding_type": "ebt_snap",
        "merchant_fns": "0256679",
        "merchant_id": "07839ae280",
        "order_ref": "3ee466e0ef",
        "payment_ref": "5fa6e45620",
        "status": "succeeded"
      }, 
      {
        "amount": "10.00",
        "funding_type": "ebt_cash",
        "merchant_fns": "0256679",
        "merchant_id": "07839ae280",
        "order_ref": "3ee466e0ef",
        "payment_ref": "sd7v223HsA",
        "status": "succeeded"
      } 
    ],
    "remaining_total": "0.00",
    "snap_total": "10.00",
    "status": "succeeded"
  },
  "ref": "72672bab12",
  "type": "ORDER_STATUS_UPDATED"
}

{
  "created": "2023-10-05T17:38:26.698516-07:00",
  "data": {
    "merchant_ref": "36e7fcecbb",
    "fns_number": "121212", 
    "name": "MerchantName", 
    "store_number": "123456",
    "address": {
      "line1": "1856 Market St.",
      "city": "San Francisco",
      "state": "CA",
      "zipcode": "94102",
      "country": "US"
    },
    "timezone_offset": -7,
    "is_physical_store": true,
    "contact_email": "[email protected]",
    "chargeback_email": "[email protected]",
    "agreed_to_tos": "2023-10-05T17:38:26.698516-07:00",
    "customer_merchant_reference": "987xy12z34",
    "go_live_date": "2023-11-05T17:38:26.698516-07:00",
  },
  "ref": "72672b13bb",
  "type": "MERCHANT_ONBOARDING_SUBMITTED",
}

{
  "created": "2023-10-05T17:38:26.698516-07:00",
  "data": {
    "merchant_ref": "36e7fcecbb",
    "fns_number": "121212", 
    "name": "MerchantName", 
    "store_number": "123456",
    "address": {
      "line1": "1856 Market St.",
      "city": "San Francisco",
      "state": "CA",
      "zipcode": "94102",
      "country": "US"
    },
    "timezone_offset": -7,
    "is_physical_store": true,
    "contact_email": "[email protected]",
    "chargeback_email": "[email protected]",
    "agreed_to_tos": "2023-10-05T17:38:26.698516-07:00",
    "customer_merchant_reference": "987xy12z34",
    "go_live_date": "2023-11-05T17:38:26.698516-07:00",
  },
  "ref": "72672b13bb",
  "type": "MERCHANT_ONBOARDING_VERIFICATION_FAILED",
}

{
  "created": "2023-10-05T17:38:26.698516-07:00",
  "data": {
    "merchant_ref": "36e7fcecbb",
    "fns_number": "121212", 
    "name": "MerchantName", 
    "store_number": "123456",
    "address": {
      "line1": "1856 Market St.",
      "city": "San Francisco",
      "state": "CA",
      "zipcode": "94102",
      "country": "US"
    },
    "timezone_offset": -7,
    "is_physical_store": true,
    "contact_email": "[email protected]",
    "chargeback_email": "[email protected]",
    "agreed_to_tos": "2023-10-05T17:38:26.698516-07:00",
    "customer_merchant_reference": "987xy12z34",
    "go_live_date": "2023-11-05T17:38:26.698516-07:00",
  },
  "ref": "72672b13bb",
  "type": "MERCHANT_ONBOARDING_LIVE",
}

{
  "created": "2023-10-05T17:38:26.698516-07:00",
  "data": {
    "amount": "10.00",
    "external_order_id": "a238d043-5d88-4bd8-bdf5-769c83e2482e",
    "funding_type": "ebt_snap",
    "merchant_fns": "121212", 
    "merchant_id": "2fb3asd",
    "payment_ref": "3a16426601",
    "status": "succeeded",
  },
  "ref": "72672b13bb",
  "type": "PAYMENT_STATUS_UPDATED",
}

{
  "ref": "cd9e3b2c83",
  "created": "2024-05-21T14:50:57.861207+00:00",
  "type": "PAYMENT_STATUS_UPDATED",
  "data": {
    "payment_ref": "2a629162f4",
    "status": "failed",
    "amount": "20.00",
    "merchant_fns": "1234567",
    "merchant_id": "4f984ec909",
    "failure_reason": {
      "code": "ebt_error_51",
      "message": "Insufficient funds - Insufficient Funds. Remaining balances are SNAP: $100.00, EBT Cash: $100.00"
    },
    "funding_type": "ebt_cash",
    "previous_errors": [
      {
        "code": "ebt_error_51",
        "message": "Insufficient funds - Insufficient Funds. Remaining balances are SNAP: $100.00, EBT Cash: $100.00",
        "details": {
          "cash_balance": "100.00",
          "snap_balance": "100.00"
        },
        "source": {
          "resource": "Payments",
          "ref": "2a629162f4"
        }
      }
    ]
  }
}

{
  "ref": "72672bc724",
  "created": "2023-10-05T17:38:26.698516-07:00",
  "type": "REFUND_STATUS_UPDATED",
  "data": {
    "refund_ref": "87432dehkk",
    "external_order_id": "a238d043-5d88-4bd8-bdf5-769c83e2482e",
    "status": "succeeded",
    "amount": "25.99",
    "merchant_fns": "121212",
    "merchant_id": "2fb3asd",
    "payment_ref": "8e3c6a9d07"
  }
}

{
  "ref": "e1ecf255f4",
  "created": "2024-01-31T19:50:10.065453+00:00",
  "type": "REFUND_STATUS_UPDATED",
  "data": {
    "refund_ref": "60ddf6e386",
    "external_order_id": "a238d043-5d88-4bd8-bdf5-769c83e2482e",
    "status": "failed",
    "amount": "20.00",
    "merchant_fns": "9000012",
    "merchant_id": "bacb08ea2a",
    "payment_ref": "234ccb21d6",
    "failure_reason": {
      "code": "55",
      "message": "Invalid PIN or PIN not selected - Invalid PIN"
    }
  }
}

{
  "created": "2023-10-05T17:38:26.698516-07:00",
  "data": {
    "ebt_cash_total": "10.00",
    "external_order_id": "58503b96-5111-495b-b13b-d9247be12e75",
    "merchant_fns": "121212",
    "merchant_id": "2fb3asd",
    "order_ref": "3ee466e0ef",
    "payments": [
      {
        "amount": "10.00",
        "funding_type": "ebt_snap",
        "merchant_fns": "0256679",
        "merchant_id": "07839ae280",
        "order_ref": "3ee466e0ef",
        "payment_ref": "5fa6e45620",
        "status": "succeeded"
      },
      {
        "amount": "10.00",
        "funding_type": "ebt_cash",
        "merchant_fns": "0256679",
        "merchant_id": "07839ae280",
        "order_ref": "3ee466e0ef",
        "payment_ref": "sd7v223HsA",
        "status": "succeeded"
      } 
    ],
    "remaining_total": "0.00",
    "snap_total": "10.00",
    "status": "succeeded"
  },
  "ref": "72672bab12",
  "type": "ORDER_STATUS_UPDATED"
}

{
  "ref": "d700e94235",
  "created": "2024-05-21T14:50:57.852878+00:00",
  "type": "ORDER_STATUS_UPDATED",
  "data": {
    "order_ref": "c8ac066123",
    "status": "failed",
    "snap_total": "0.00",
    "ebt_cash_total": "20.00",
    "remaining_total": "0.00",
    "merchant_fns": "1234789",
    "merchant_id": "4f984ec818",
    "failure_reason": {
      "code": "ebt_error_51",
      "message": "Insufficient funds - Insufficient Funds. Remaining balances are SNAP: $100.00, EBT Cash: $100.00"
    },
    "payments": [
      {
        "payment_ref": "2a629165G6",
        "status": "failed",
        "amount": "20.00",
        "merchant_fns": "1234567",
        "merchant_id": "4f984ec909",
        "order_ref": "c8ac066123",
        "failure_reason": {
          "code": "ebt_error_51",
          "message": "Insufficient funds - Insufficient Funds. Remaining balances are SNAP: $100.00, EBT Cash: $100.00"
        },
        "funding_type": "ebt_cash"
      }
    ],
    "previous_errors": [
      {
        "code": "ebt_error_51",
        "message": "Insufficient funds - Insufficient Funds. Remaining balances are SNAP: $100.00, EBT Cash: $100.00",
        "details": {
          "cash_balance": "100.00",
          "snap_balance": "100.00"
        },
        "source": {
          "resource": "Payments",
          "ref": "2a629162f4"
        }
      }
    ]
  }
}

{
  "created": "2023-10-05T17:38:26.698516-07:00",
  "data": {
    "amount": "10.00",
    "external_order_id": "a238d043-5d88-4bd8-bdf5-769c83e2482e",
    "funding_type": "ebt_snap",
    "merchant_fns": "121212", 
    "merchant_id": "2fb3asd",
    "payment_ref": "3a16426601",
    "status": "succeeded",
    "order_ref": "3a16426601"
  },
  "ref": "72672b13bb",
  "type": "PAYMENT_STATUS_UPDATED",
}

{
  "ref": "cd9e3b2c83",
  "created": "2024-05-21T14:50:57.861207+00:00",
  "type": "PAYMENT_STATUS_UPDATED",
  "data": {
    "payment_ref": "2a629162f4",
    "status": "failed",
    "amount": "20.00",
    "merchant_fns": "1234567",
    "merchant_id": "4f984ec909",
    "order_ref": "c8ac066560",
    "failure_reason": {
      "code": "ebt_error_51",
      "message": "Insufficient funds - Insufficient Funds. Remaining balances are SNAP: $100.00, EBT Cash: $100.00"
    },
    "funding_type": "ebt_cash",
    "previous_errors": [
      {
        "code": "ebt_error_51",
        "message": "Insufficient funds - Insufficient Funds. Remaining balances are SNAP: $100.00, EBT Cash: $100.00",
        "details": {
          "cash_balance": "100.00",
          "snap_balance": "100.00"
        },
        "source": {
          "resource": "Payments",
          "ref": "2a629162f4"
        }
      }
    ]
  }
}

{
  "ref": "72672bc724",
  "created": "2023-10-05T17:38:26.698516-07:00",
  "type": "REFUND_STATUS_UPDATED",
  "data": {
    "refund_ref": "87432dehkk",
    "external_order_id": "a238d043-5d88-4bd8-bdf5-769c83e2482e",
    "status": "succeeded",
    "amount": "25.99",
    "merchant_fns": "121212",
    "merchant_id": "2fb3asd",
    "payment_ref": "8e3c6a9d07", 
    "order_ref": "3a16426601"
  }
}

{
  "ref": "e1ecf255f4",
  "created": "2024-01-31T19:50:10.065453+00:00",
  "type": "REFUND_STATUS_UPDATED",
  "data": {
    "refund_ref": "60ddf6e386",
    "external_order_id": "a238d043-5d88-4bd8-bdf5-769c83e2482e",
    "status": "failed",
    "amount": "20.00",
    "merchant_fns": "9000012",
    "merchant_id": "bacb08ea2a",
    "payment_ref": "234ccb21d6",
    "order_ref": "3a16426601",
    "failure_reason": {
      "code": "55",
      "message": "Invalid PIN or PIN not selected - Invalid PIN"
    }
  }
}

# Python Django Example
@api_view(http_method_names=["POST"])
def handle_webhook(request):
    event = request.data
    received_signature = request.headers.get("Webhook-Signature")
    # Validate signature (more instructions in Step 3)

    event_type = event["type"]

    # Handle the event
    if event_type == "ORDER_STATUS_UPDATED":
        # do something with order
        order_ref = event["data"]["order_ref"]
        pass
    elif event_type == "PAYMENT_STATUS_UPDATED":
        payment_ref = event["data"]["payment_ref"]
        pass
    elif event_type == "REFUND_STATUS_UPDATED":
        refund_ref = event["data"]["refund_ref"]
        pass

    # Return a 200 response to acknowledge receipt of the event
    return HttpResponse(status=200)

// Java Spring Example
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class WebhookController {

    @PostMapping("/mywebhookendpoint")
    public ResponseEntity<String> handleRequest(@RequestBody MyRequestData requestData, HttpServletRequest request) {
        String received_signature = request.getHeader("Webhook-Signature");
				// Validate signature (more instructions in Step 3)

        String eventType = requestData.getType();
        
        // Handle the event
				switch (eventType) {
						case "ORDER_STATUS_UPDATED": {
                break;
              }
						case "PAYMENT_STATUS_UPDATED": {
								break;
							}
						case "REFUND_STATUS_UPDATED": {
								break;
							}
						default:
								System.out.println("Webhook Event is unhandled");
				}
        
        // Return a 200 response to acknowledge receipt of the event
        String responseBody = "Processed Webhook";
        return new ResponseEntity<>(responseBody, HttpStatus.OK);
    }
}

// Node Example
const express = require('express');
const app = express();

app.post('/mywebhookendpoint', express.raw({type: 'application/json'}), (request, response) => {
  const signature = request.headers['Webhook-Signature'];
	// Validate signature (more instructions in Step 3)

  let event;

	event = request.body

	// Handle the event
	  switch (event.type) {
	    case 'ORDER_STATUS_UPDATED':
	      const orderRef = event.data.order_ref;
	      // Handle order ref
	      break;
	    case 'PAYMENT_STATUS_UPDATED':
				const paymentRef = event.data.payment_ref
				// Handle payment ref
				break;
	    case 'REFUND_STATUS_UPDATED':
				const refundRef = event.data.refund_ref
				// Handle refund ref
				break;
	    default:
	      console.log(`Event type ${event.type} not handled`);
	  }

  // Return a 200 response to acknowledge receipt of the event
  response.send();
});

require 'json'
require 'sinatra'
​
post '/webhook' do
  event = JSON.parse(request.body.read)
  received_signature = request.env['Webhook-Signature']
  # Validate signature (more instructions in Step 3)
​
  event_type = event['type']
​
  # Handle the event
  case event_type
  when 'ORDER_STATUS_UPDATED'
    # do something with order
    order_ref = event['data']['order_ref']
  when 'PAYMENT_STATUS_UPDATED'
    payment_ref = event['data']['payment_ref']
  when 'REFUND_STATUS_UPDATED'
    refund_ref = event['data']['refund_ref']
  end
  
  # Return a 200 response to acknowledge receipt of the event
  status 200
end

import hashlib
import hmac

def get_hmac_string(secret, message):
    return hmac.new(
        secret.encode("utf-8"),
        message.encode("utf-8"),
        hashlib.sha256,
    ).hexdigest()

# Django example
@api_view(http_method_names=["POST"])
def webhook_view(request):
    webhook_payload = request.body # ie. "{\"ref\": \"6ce5bdb204\", \"created\": \"2023-06-23T18:48:13.791077+00:00\", \"type\": \"ORDER_STATUS_UPDATED\", \"data\": {\"order_ref\": \"3b96a5312a\", \"status\": \"canceled\", \"snap_total\": \"20.00\", \"ebt_cash_total\": \"20.00\", \"remaining_total\": \"0.00\"}}"
    my_secret = "wh_secretabc123"
    # Compute expected signature
    expected_signature = get_hmac_string(my_secret, webhook_payload)
  
    received_signature = request.headers.get("Webhook-Signature")
  
    # Assert that computed signature above equals Webhook-Signature header using constant-time string comparison
    if not hmac.compare_digest(expected_signature, received_signature):
        raise SignatureError()

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;
import java.security.InvalidKeyException;
import java.security.NoSuchAlgorithmException;
import java.security.MessageDigest;

public class WebhookHandler {
    
    public static String getHmacString(String secret, String message) throws NoSuchAlgorithmException, InvalidKeyException {
        Mac sha256Hmac = Mac.getInstance("HmacSHA256");
        SecretKeySpec secretKey = new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), "HmacSHA256");
        sha256Hmac.init(secretKey);
        byte[] hmacBytes = sha256Hmac.doFinal(message.getBytes(StandardCharsets.UTF_8));
        StringBuilder hexString = new StringBuilder();
        for (byte hmacByte : hmacBytes) {
            String hex = Integer.toHexString(0xff & hmacByte);
            if (hex.length() == 1) hexString.append('0');
            hexString.append(hex);
        }
        return hexString.toString();
    }
  
    public static boolean constantTimeEquals(String str1, String str2) throws NoSuchAlgorithmException {
        byte[] digest1 = getDigest(str1);
        byte[] digest2 = getDigest(str2);

        // Compare the digests using MessageDigest.isEqual()
        return MessageDigest.isEqual(digest1, digest2);
    }

    // Spring Boot example
    @PostMapping("/webhook")
    public void webhookHandler(@RequestBody String webhookPayload, @RequestHeader("Webhook-Signature") String receivedSignature) {
        String mySecret = "wh_secretabc123";
        try {
            // Compute expected signature
            String expectedSignature = getHmacString(mySecret, webhookPayload);

            // Assert that computed signature above equals Webhook-Signature header using constant-time string comparison
            if (!constantTimeEquals(expectedSignature, receivedSignature)) {
                throw new SignatureError();
            }
            
            // Process the webhook payload
            // ...
        } catch (Exception e) {
            // Handle the exception
            e.printStackTrace();
        }
    }
}

const crypto = require('crypto');

function getHmacString(secret, message) {
  const hmac = crypto.createHmac('sha256', secret);
  hmac.update(message, 'utf8');
  return hmac.digest('hex');
}

// Express example
app.post('/webhook', (req, res) => {
  const webhookPayload = req.body.toString(); // assuming the request body contains the JSON payload
  const mySecret = 'wh_secretabc123';
  
  try {
    // Compute expected signature
    const expectedSignature = getHmacString(mySecret, webhookPayload);
  
    const receivedSignature = req.headers['webhook-signature'];
  
    // Assert that computed signature above equals Webhook-Signature header using constant-time string comparison
    if (!crypto.timingSafeEqual(Buffer.from(expectedSignature, 'hex'), Buffer.from(receivedSignature, 'hex'))) {
      throw new Error('SignatureError');
    }
  
    // Process the webhook payload
    // ...
  
    res.sendStatus(200);
  } catch (error) {
    // Handle the error
    res.status(500).send(error.message);
  }
});

require 'openssl'
require 'base64'
require 'sinatra'

def get_hmac_string(secret, message)
  digest = OpenSSL::Digest.new('sha256')
  hmac = OpenSSL::HMAC.hexdigest(digest, secret, message)
  hmac
end

# Sinatra example
post '/webhook' do
  webhook_payload = request.body.read
  my_secret = 'wh_secretabc123'
  
  # Compute expected signature
  expected_signature = get_hmac_string(my_secret, webhook_payload)
  
  received_signature = request.env['HTTP_WEBHOOK_SIGNATURE']
  
  # Assert that computed signature above equals Webhook-Signature header using constant-time string comparison
  unless Rack::Utils.secure_compare(expected_signature, received_signature)
    raise 'SignatureError'
  end
  
  # Process the webhook payload
  # ...
  
  status 200
end