Main API Docs
  • Welcome!
  • General
    • Introduction
    • Authentication
    • Personal Access Tokens
    • Test IDs
    • Check Wallet Balance
  • Appruve Identity
    • Introduction
    • Ghana 🇬🇭
      • Verify Ghana TIN
      • Verify Ghana Driver License
      • Verify Ghana SSNIT ID
      • Verify Ghana Passport
      • Verify Ghana Voter ID
      • Verify Ghana Digital Address
    • Nigeria 🇳🇬
      • Verify Nigeria TIN
      • Verify Nigeria Driver License
      • Verify Nigeria NIN
      • Verify Nigeria vNIN
      • Verify Nigeria Voter ID
      • Verify Nigeria BVN
    • Kenya 🇰🇪
      • Verify Kenya KRA PIN
      • Verify Kenya National ID
    • Uganda 🇺🇬
      • Verify Uganda Voter ID
      • Verify Uganda Telco Subscriber
      • BulK Uganda Telco Subscriber Verification
  • Appruve Business
    • Introduction
    • Business Lookups
      • Nigeria 🇳🇬
        • Lookup with CAC number
        • Lookup using Tax ID (TIN)
      • Uganda Business Lookup 🇺🇬
      • Ghana Business Lookup 🇬🇭
    • Business Beneficial Ownership
      • Nigeria 🇳🇬
  • Appruve Agency
    • OCR For Sequential Verification
      • Senegal 🇸🇳
      • Nigeria 🇳🇬
      • Ghana 🇬🇭
      • Kenya 🇰🇪
      • Côte d'Ivoire 🇨🇮
      • Cameroon 🇨🇲
    • Standalone OCR
      • Nigeria 🇳🇬
      • Ghana 🇬🇭
      • Kenya 🇰🇪
      • Côte d'Ivoire 🇨🇮
      • Cameroon 🇨🇲
      • Senegal 🇸🇳
    • Perform Face Matching
    • Upload Selfie Photo
    • Get Liveness Detection Challenge
    • Verify Liveness Detection Challenge
    • Confirm Extracted ID Number
    • Verify Business Document By OCR
    • Verify Nigeria vNIN with selfie
  • Guides
    • Webhooks
    • ID Document to Selfie Matching
  • Mobile Sdks
    • Android SDK
    • iOS SDK
  • Resources
    • Country Codes
    • ID Types
    • Face Liveness Check
Powered by GitBook
On this page
  • Receive Event Notifications With Webhooks
  • Build a webhook endpoint
  • Check the webhook signatures
  1. Guides

Webhooks

Receive event notifications

PreviousVerify Nigeria vNIN with selfieNextID Document to Selfie Matching

Last updated 3 years ago

Receive Event Notifications With Webhooks

Appruve uses webhooks to notify your application when an event happens in your account. Webhooks are particularly useful for asynchronous events like when a verification is completed or cancelled by a customer.

Begin using webhooks with your Appruve integration in just two steps:

Build a webhook endpoint

The first step to adding webhooks to your Appruve integration is to build your own custom endpoint. This endpoint would be a standard POST endpoint that accepts external requests. Appruve signs the webhook events it sends to your endpoints by including a signature in each event’s Appruve-Signature header. This allows you to verify that the events were sent by Appruve, not by a third party.

Check the webhook signatures

Before you can verify signatures, you need to retrieve your endpoint’s secret from your Dashboard’s . Select an endpoint that you want to obtain the secret for, then click the Click to reveal button to obtain the secret.

The Appruve-Signature header included in each signed event contains a timestamp and a signature. The timestamp is prefixed by t=, and the signature is prefixed s=.

"t=1588750909,s=c1e658b79c7abb9a840886cb3288d3b2aa316eb158fcee4e1e71fb96e92f6761"

Appruve generates signatures using a hash-based message authentication code (HMAC) with SHA-256. Follow the steps below to verify the signature.

STEP 1: EXTRACT THE TIMESTAMP AND SIGNATURE FROM THE HEADER

Split the header, using the , character as the separator, to get a list of elements. Then split each element, using the = character as the separator, to get a prefix and value pair. The value for the prefix t corresponds to the timestamp, and s corresponds to the signature.

STEP 2: PREPARE THE SIGNED_PAYLOAD STRING

The signed_payload string is created by concatenating:

  • The timestamp (as a string)

  • The character .

  • The actual JSON payload (i.e., the request body)

STEP 3: DETERMINE THE EXPECTED SIGNATURE

Compute an HMAC with the SHA256 hash function. Use the endpoint’s signing secret as the key, and use the signed_payload string as the message.

STEP 4: COMPARE THE SIGNATURES

Compare the signature in the header to the expected signature. For an equality match, compute the difference between the current timestamp and the received timestamp, then decide if the difference is within your tolerance. To protect against timing attacks, use a constant-time string comparison to compare the expected signature to each of the received signatures.

Checkout an example implementation in Ruby below.

def signature(key:, data:)
  digest = OpenSSL::Digest.new('sha256')
  OpenSSL::HMAC.hexdigest(digest, key, data)
end

def secure_compare(a, b)
  return false unless a.bytesize == b.bytesize

  l = a.unpack "C#{a.bytesize}"

  res = 0
  b.each_byte { |byte| res |= byte ^ l.shift }
  res == 0
end

def valid_signature?
  signing_secret = ENV['APPRUVE_SIGNING_SECRET']
  payload = request.body.read

  # Extract the timestamp and signatures from the header
  signature_header = request.headers['Appruve-Signature']
  parts = signature_header.split(',')
  timestamp = parts[0].split('=')[1]
  signature_from_req = parts[1].split('=')[1]

  # Prepare the signed_payload string
  signed_payload = timestamp.to_s + "." + payload

  # Determine the expected signature
  computed_signature = signature(key: signing_secret, data: signed_payload)

  # Compare the signatures
  if secure_compare(computed_signature, signature_from_req)
    return true
  else
    return false
  end
end
Add
Webhooks settings