Hands-on lab — Day 26: Webhooks and Event-Driven APIs

#!/usr/bin/env bash
# Day 026 lab — Simulate a Webhook Delivery (completed reference implementation).
#
# A real webhook needs a public server that another company's system can reach.
# You do not have one, so this script plays BOTH roles on your own machine:
#   1. SENDER  — compute the HMAC signature for a sample event payload.
#   2. RECEIVER — POST the payload to a free echo service (httpbin.org) so you
#      can see exactly what a webhook receiver would receive, then recompute
#      and compare the signature (accept a genuine one, reject a forged one).
#   3. RELIABILITY — run a retry loop that re-POSTs on a simulated non-2xx
#      status and stops once it gets a 2xx acknowledgement.
#
# Run from the lab directory:  bash examples/webhook_demo.sh
#
# The signature and verify steps are LOCAL and need no network. The delivery
# step reaches https://httpbin.org; offline, it degrades with a clear message
# and the script still exits 0.
set -u

# The sample event. printf '%s' (below) prints it with NO trailing newline, so
# the bytes we SIGN are exactly the bytes we SEND — this matters for HMAC.
PAYLOAD='{"event":"invoice.paid","id":"evt_28a7","data":{"amount":4200,"currency":"usd"}}'

# A FAKE secret, for the demo only. A real secret is a credential: keep it out
# of source code and logs (see security.md).
SECRET='whsec_demo_do_not_use_in_production'

HTTPBIN='https://httpbin.org'

rule() { printf '\n=== %s ===\n' "$1"; }

# Compute HMAC-SHA-256 of stdin with the given key; print just the 64-hex digest.
hmac_sha256() {
  local key="$1"
  openssl dgst -sha256 -hmac "$key" | sed 's/^.*= //'
}

# Return 0 if httpbin appears reachable, else 1.
have_network() {
  curl -s -o /dev/null --max-time 12 "${HTTPBIN}/get" 2>/dev/null
}

# ---------------------------------------------------------------------------
# 1. What the SENDER does: sign the raw payload.
# ---------------------------------------------------------------------------
show_sign() {
  rule "1. Compute the webhook signature (what the SENDER does)"
  local sig
  sig="$(printf '%s' "${PAYLOAD}" | hmac_sha256 "${SECRET}")"
  echo "payload: ${PAYLOAD}"
  echo "signature: sha256=${sig}"
  echo "(${#sig} hex characters)"
}

# ---------------------------------------------------------------------------
# 2. What the RECEIVER sees: deliver to an echo endpoint.
# ---------------------------------------------------------------------------
show_deliver() {
  rule "2. Deliver the payload to an echo endpoint (what the RECEIVER sees)"
  local sig response
  sig="$(printf '%s' "${PAYLOAD}" | hmac_sha256 "${SECRET}")"
  if ! have_network; then
    echo "OFFLINE: could not reach ${HTTPBIN}. Skipping the live delivery."
    echo "(The signature and verify steps above and below need no network.)"
    return
  fi
  # A real webhook is exactly this: a POST with a JSON body, a Content-Type,
  # an event-type header, and a signature header. httpbin echoes it all back,
  # so its response shows what a receiver would parse. -f fails on HTTP errors;
  # --retry with --retry-all-errors rides past httpbin's frequent transient
  # gateway hiccups and transfer resets (a real sender retries too).
  response="$(curl -sf --max-time 25 --retry 6 --retry-delay 2 --retry-all-errors \
    -X POST "${HTTPBIN}/post" \
    -H 'Content-Type: application/json' \
    -H 'X-Webhook-Event: invoice.paid' \
    -H "X-Webhook-Signature: sha256=${sig}" \
    -d "${PAYLOAD}" 2>/dev/null)" || response=""
  if [ -z "${response}" ]; then
    echo "(could not reach ${HTTPBIN} — transient error; try again in a moment)"
    return
  fi
  # Pull the echoed body and signature header back out of httpbin's JSON with
  # grep/sed only (no jq dependency).
  echo "the receiver received this body:"
  printf '%s\n' "${response}" | sed -n 's/.*"data": "\(.*\)", *$/\1/p' | sed 's/\\"/"/g' | head -n 1
  echo "and this signature header:"
  printf '%s\n' "${response}" | sed -n 's/.*"X-Webhook-Signature": "\(sha256=[0-9a-f]*\)".*/\1/p' | head -n 1
}

# ---------------------------------------------------------------------------
# 3. Verify (recompute + compare) and retry on non-2xx.
# ---------------------------------------------------------------------------
show_verify_and_retry() {
  rule "3. Verify + retry"
  local sent_sig recomputed tampered_payload tampered_sig
  sent_sig="$(printf '%s' "${PAYLOAD}" | hmac_sha256 "${SECRET}")"

  # The RECEIVER recomputes the signature over the body it got and compares.
  recomputed="$(printf '%s' "${PAYLOAD}" | hmac_sha256 "${SECRET}")"
  if [ "${sent_sig}" = "${recomputed}" ]; then
    echo "receiver recomputes signature over the body it got... MATCH -> would reply 200 OK"
  else
    echo "receiver recomputes signature over the body it got... MISMATCH -> reject"
  fi

  # A forged/tampered body recomputes to a DIFFERENT signature -> rejected.
  tampered_payload='{"event":"invoice.paid","id":"evt_28a7","data":{"amount":999999,"currency":"usd"}}'
  tampered_sig="$(printf '%s' "${tampered_payload}" | hmac_sha256 "${SECRET}")"
  if [ "${sent_sig}" = "${tampered_sig}" ]; then
    echo "tampered payload recomputes to the SAME signature... (should not happen)"
  else
    echo "tampered payload recomputes to a different signature... MISMATCH -> reject (forged)"
  fi

  # A sender retries until it gets a 2xx. We SIMULATE a receiver that fails
  # twice (503) then succeeds (200), to show at-least-once retrying + backoff.
  local -a statuses=(503 503 200)
  local attempt=1 code
  for code in "${statuses[@]}"; do
    if [ "${code}" -ge 200 ] && [ "${code}" -lt 300 ]; then
      echo "attempt ${attempt}: server returned ${code} -> acknowledged, stop retrying"
      break
    else
      echo "attempt ${attempt}: server returned ${code} -> not 2xx, retrying after backoff..."
    fi
    attempt=$((attempt + 1))
  done
}

main() {
  echo "Day 026 — Simulate a Webhook Delivery"
  echo "Playing both sender and receiver locally; echo endpoint: ${HTTPBIN}/post"
  show_sign
  show_deliver
  show_verify_and_retry
  echo
  echo "Done. You signed a payload, saw what a receiver receives, verified a"
  echo "genuine signature, rejected a forged one, and watched retries back off."
}

main "$@"

lesson_id: D026
day: 26
kind: api-example
languages: [bash]
setup_commands:
  - cd labs/sections/computing-foundations/day-026-webhooks-and-event-driven-apis
run_commands:
  - bash examples/webhook_demo.sh
  - bash starter/webhook_demo.sh
test_commands:
  - bash tests/run_tests.sh
cleanup_commands:
  - 'git checkout -- starter/webhook_demo.sh  # optional: reset your work'
requires_network: true
requires_api_key: false
estimated_minutes: 30
last_executed: '2026-07-12'
executed_on: 'macOS (curl 8.7.1, OpenSSL 3.6.3), online, bash tests/run_tests.sh → 15 checks, 0 failure(s), 0 skip(s)'

# Dependencies — Day 026 lab

**`curl` and `openssl` only** — both preinstalled on macOS and mainstream
Linux (and available on Windows 10+ / WSL). No package installs, no accounts,
no API keys.

- `curl` — makes the sample webhook delivery (a `POST`) to a public echo
  service so you can see what a receiver receives.
- `openssl` — computes the HMAC-SHA-256 signature that authenticates a
  webhook, exactly as a real sender and receiver would.

The lab reaches one free public test service — `https://httpbin.org` — for the
live delivery step, so that step needs network access. Everything else (the
signature computation, the verify-and-compare, the retry simulation) is
**local** and works offline. With no network the scripts print a clear message
and the tests **skip** (never fail) the live delivery check, still verifying
the HMAC locally. No `sudo` required.

#!/usr/bin/env bash
# Day 026 starter — Simulate a Webhook Delivery.
#
# Complete the FOUR exercises below. Each names the exact command to use.
# You will play both sides of a webhook: the SENDER that signs and delivers a
# payload, and the RECEIVER that verifies it. The completed reference is in
# ../examples/webhook_demo.sh — try to build it yourself first.
#
# Run from the lab directory:  bash starter/webhook_demo.sh
set -u

# The sample event. Use printf '%s' (NOT echo) so no trailing newline is added
# and the bytes you SIGN are exactly the bytes you SEND.
PAYLOAD='{"event":"invoice.paid","id":"evt_28a7","data":{"amount":4200,"currency":"usd"}}'

# A FAKE secret, for the demo only. Never hard-code a real secret (see security.md).
SECRET='whsec_demo_do_not_use_in_production'

HTTPBIN='https://httpbin.org'

rule() { printf '\n=== %s ===\n' "$1"; }

echo "Day 026 starter — Simulate a Webhook Delivery"

# ---------------------------------------------------------------------------
# Exercise 1: compute the signature (what the SENDER does).
# Replace the echo with:
#   printf '%s' "$PAYLOAD" | openssl dgst -sha256 -hmac "$SECRET"
# It should print a 64-hex-character digest.
# ---------------------------------------------------------------------------
rule "1. Compute the signature"
echo "EXERCISE — your turn: HMAC-SHA-256 the PAYLOAD with the SECRET"

# ---------------------------------------------------------------------------
# Exercise 2: deliver the payload to the echo endpoint (what the RECEIVER sees).
# Replace the echo with a POST that carries the body and a signature header:
#   sig=$(printf '%s' "$PAYLOAD" | openssl dgst -sha256 -hmac "$SECRET" | sed 's/^.*= //')
#   curl -sf --max-time 25 --retry 6 --retry-delay 2 --retry-all-errors \
#     -X POST "$HTTPBIN/post" \
#     -H 'Content-Type: application/json' \
#     -H 'X-Webhook-Event: invoice.paid' \
#     -H "X-Webhook-Signature: sha256=$sig" \
#     -d "$PAYLOAD"
# httpbin echoes your body and headers back — that echo is what a receiver parses.
# ---------------------------------------------------------------------------
rule "2. Deliver to the echo endpoint"
echo "EXERCISE — your turn: POST the PAYLOAD to $HTTPBIN/post and read the echo"

# ---------------------------------------------------------------------------
# Exercise 3: verify by recomputing and comparing (what the RECEIVER does).
# Replace the echo with:
#   sent=$(printf '%s'   "$PAYLOAD" | openssl dgst -sha256 -hmac "$SECRET" | sed 's/^.*= //')
#   recomputed=$(printf '%s' "$PAYLOAD" | openssl dgst -sha256 -hmac "$SECRET" | sed 's/^.*= //')
#   [ "$sent" = "$recomputed" ] && echo "MATCH -> accept" || echo "MISMATCH -> reject"
# Then repeat with a TAMPERED payload (change 4200 to 999999) and confirm it MISMATCHES.
# ---------------------------------------------------------------------------
rule "3. Verify the signature"
echo "EXERCISE — your turn: recompute the signature and compare; then try a tampered body"

# ---------------------------------------------------------------------------
# Exercise 4: simulate a retry loop (what the SENDER does on a non-2xx).
# Replace the echo with a loop over simulated statuses that stops on a 2xx:
#   for code in 503 503 200; do
#     if [ "$code" -ge 200 ] && [ "$code" -lt 300 ]; then
#       echo "returned $code -> acknowledged, stop retrying"; break
#     else
#       echo "returned $code -> not 2xx, retrying after backoff..."
#     fi
#   done
# ---------------------------------------------------------------------------
rule "4. Retry on non-2xx"
echo "EXERCISE — your turn: loop over 503 503 200 and stop retrying on the 200"

echo
echo "When all four are done, compare your output with ../examples/webhook_demo.sh"

# Webhook worksheet — Day 026

Run the commands (from the examples or your completed starter) and record what
YOUR run produced. The signature is deterministic, so it will match everyone
else's for the same payload and secret — but the echo response and trace ID
are unique to your run.

Sample event used:
`{"event":"invoice.paid","id":"evt_28a7","data":{"amount":4200,"currency":"usd"}}`
Secret used: `whsec_demo_do_not_use_in_production`

## 1. The signature your payload + secret produces

- Command: `printf '%s' "$PAYLOAD" | openssl dgst -sha256 -hmac "$SECRET"`
- Signature (paste the full value): `sha256=____`
- How many characters is the hex digest? `____`  (should be 64)

## 2. What the echo endpoint reported back

Paste the body the receiver received:

```
____
```

Paste at least one header the receiver saw (e.g. `X-Webhook-Event` or
`X-Webhook-Signature`):

```
____
```

## 3. One reason webhooks retry

- In your own words, one concrete reason a webhook sender retries a delivery:

> _your answer here_

- The problem retrying creates for a receiver, and the property that solves it
  (name it):

> _your answer here_

## 4. Tampering detection

Change one character of the payload (for example `4200` → `999999`), re-run the
signature step, and answer:

- How much of the signature changed? `____`
- Why does that make tampering detectable?

> _your answer here_

#!/usr/bin/env bash
# Tests for the Day 026 lab. Run from the lab directory:
#   bash tests/run_tests.sh
#
# Two kinds of checks:
#   * Structure + LOCAL checks always run and must pass: files present, both
#     scripts parse, the example exercises each core step, the starter names
#     its four exercises, and — with NO network — the HMAC signature computes
#     to the known 64-hex value (this is pure openssl, no internet).
#   * The NETWORK check runs only when httpbin.org is reachable: it POSTs the
#     payload and confirms the echo contains it. Offline, or when httpbin is
#     transiently down, that check is SKIPPED (never failed).
#
# The script exits 0 when no non-skipped check failed, online or offline.
set -u

lab_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
HTTPBIN='https://httpbin.org'
PAYLOAD='{"event":"invoice.paid","id":"evt_28a7","data":{"amount":4200,"currency":"usd"}}'
SECRET='whsec_demo_do_not_use_in_production'
EXPECTED_SIG='cadd3bf8973d72aec386c06d46c8803f68aa1f6936e9ee4a334adedace74e3c0'

failures=0
checks=0
skips=0

pass() { checks=$((checks + 1)); echo "  ok:   $1"; }
fail() { checks=$((checks + 1)); failures=$((failures + 1)); echo "  FAIL: $1"; }
skip() { skips=$((skips + 1)); echo "  skip: $1"; }

example="${lab_dir}/examples/webhook_demo.sh"
starter="${lab_dir}/starter/webhook_demo.sh"

echo "== Structure checks =="
[ -f "${example}" ] && pass "example script exists" || fail "example script missing"
[ -f "${starter}" ] && pass "starter script exists" || fail "starter script missing"
[ -f "${lab_dir}/starter/webhook-worksheet.md" ] && pass "worksheet exists" || fail "worksheet missing"

# The example must exercise each core step.
for needle in "openssl dgst -sha256 -hmac" "curl" "X-Webhook-Signature" "MISMATCH" "retrying"; do
  if grep -q -- "${needle}" "${example}"; then pass "example uses '${needle}'"; else fail "example missing '${needle}'"; fi
done

# The starter must name its four numbered exercises.
ex_count="$(grep -cE 'Exercise [1-4]' "${starter}" 2>/dev/null || true)"
if [ "${ex_count:-0}" -ge 4 ]; then pass "starter has 4 numbered exercises"; else fail "starter has 4 numbered exercises (found ${ex_count:-0})"; fi

# Both scripts must be valid bash.
if bash -n "${example}" 2>/dev/null; then pass "example has valid bash syntax"; else fail "example has a syntax error"; fi
if bash -n "${starter}" 2>/dev/null; then pass "starter has valid bash syntax"; else fail "starter has a syntax error"; fi

echo
echo "== Local HMAC checks (no network) =="
# Recompute the signature exactly as sender and receiver would.
sig="$(printf '%s' "${PAYLOAD}" | openssl dgst -sha256 -hmac "${SECRET}" | sed 's/^.*= //')"
# It must be exactly 64 lowercase hex characters.
if printf '%s' "${sig}" | grep -qE '^[0-9a-f]{64}$'; then
  pass "HMAC signature is a 64-hex-character string"
else
  fail "HMAC signature is not 64 hex characters (got '${sig}')"
fi
# It must equal the known, deterministic value for this payload+secret.
if [ "${sig}" = "${EXPECTED_SIG}" ]; then
  pass "HMAC signature matches the expected deterministic value"
else
  fail "HMAC signature != expected (got '${sig}')"
fi
# Tampering must change the signature (integrity property).
tampered="$(printf '%s' '{"event":"invoice.paid","id":"evt_28a7","data":{"amount":999999,"currency":"usd"}}' | openssl dgst -sha256 -hmac "${SECRET}" | sed 's/^.*= //')"
if [ "${sig}" != "${tampered}" ]; then
  pass "a tampered payload produces a different signature (rejected)"
else
  fail "tampered payload should not match the original signature"
fi

echo
echo "== Network check (httpbin echo) =="
if ! curl -s -o /dev/null --max-time 12 "${HTTPBIN}/get" 2>/dev/null; then
  skip "no network access — skipping the live delivery echo check (expected offline)"
else
  echoed="$(curl -sf --max-time 25 --retry 6 --retry-delay 2 --retry-all-errors \
    -X POST "${HTTPBIN}/post" \
    -H 'Content-Type: application/json' \
    -H "X-Webhook-Signature: sha256=${sig}" \
    -d "${PAYLOAD}" 2>/dev/null)" || echoed=""
  if [ -z "${echoed}" ]; then
    skip "delivery check — httpbin transiently unavailable; retry later"
  elif printf '%s' "${echoed}" | grep -q 'invoice.paid' \
    && printf '%s' "${echoed}" | grep -q "${sig}"; then
    pass "the echo endpoint returned our payload and signature header"
  else
    fail "the echo endpoint should echo our payload and signature"
  fi
fi

echo
echo "${checks} checks, ${failures} failure(s), ${skips} skip(s)."
[ "${failures}" -eq 0 ]