Implementing Webhook Logic

1. Designing Webhook Subscription System

FieldDetail
idSubscription UUID
tenant/userOwner
urlTarget endpoint (HTTPS)
eventsSubscribed event types
secretHMAC signing key
statusactive / paused / disabled

2. Implementing Webhook Delivery Logic

Example: Async POST

public DeliveryResult deliver(Subscription sub, Event e) {
    var body = mapper.writeValueAsBytes(e);
    var sig  = sign(sub.secret(), body, e.id(), Instant.now());
    var req  = HttpRequest.newBuilder(URI.create(sub.url()))
        .header("Content-Type", "application/json")
        .header("X-Signature", sig)
        .header("X-Event-Id", e.id())
        .timeout(Duration.ofSeconds(10))
        .POST(BodyPublishers.ofByteArray(body))
        .build();
    var resp = httpClient.send(req, BodyHandlers.discarding());
    return new DeliveryResult(resp.statusCode(), resp.headers());
}

3. Implementing Webhook Signing

Example: HMAC-SHA256

String stringToSign = timestamp + "." + new String(body, UTF_8);
byte[] mac = hmacSha256(secret.getBytes(), stringToSign.getBytes());
String header = "t=" + timestamp + ",v1=" + Hex.encode(mac);

4. Implementing Webhook Verification (Server)

StepDetail
Parse headerExtract timestamp + signature
Reconstructtimestamp + "." + raw body
HMAC compareConstant-time
Reject staleWithin ±5 minutes
Reject duplicateTrack seen event IDs

5. Implementing Retry Logic with Exponential Backoff

AttemptDelay
1Immediate
2+1 min
3+5 min
4+30 min
5+2 h
6++12 h, up to 24-72 h max

6. Implementing Webhook Delivery Tracking

RecordDetail
attemptsStatus + response code each try
latencyFor monitoring slow consumers
last statusSurfaced in subscriber UI
payload snapshotFor replay

7. Implementing Webhook Failure Handling

PolicyDetail
Auto-disableAfter N consecutive failures (e.g., 24h)
Notify subscriberEmail on disable
Manual replayUI button to retry
Health endpointSubscriber status page

8. Implementing Webhook Event Filtering

FilterDetail
Event typesSubscribe to subset
Resource scopePer project/tenant
Conditionse.g., only orders > $100
Field maskLimit payload fields

9. Implementing Webhook Replay

MechanismDetail
Store raw eventImmutable for window (e.g., 30 days)
Replay endpointResend by event ID or range
Idempotency keySame event ID; consumer dedupes

10. Implementing Webhook Security

PracticeDetail
HTTPS onlyReject http:// URLs
SignatureHMAC required
TimestampReplay defense
SSRF guardBlock internal IPs / metadata endpoints
Allow-listed IPsPublish source ranges for subscribers

11. Implementing Webhook Rate Limiting

PerDetail
EndpointCap per-URL deliveries/sec
SubscriptionLimit per-subscription queue depth
TenantFair share globally
BackpressurePause on subscriber 429s

12. Implementing Webhook Logging

FieldDetail
event id, typeCorrelation
subscription id, urlTarget
attempt #, status, latencyPer try
response excerptFirst N bytes for debugging