Implementing Webhook Logic
1. Designing Webhook Subscription System
| Field | Detail |
|---|---|
| id | Subscription UUID |
| tenant/user | Owner |
| url | Target endpoint (HTTPS) |
| events | Subscribed event types |
| secret | HMAC signing key |
| status | active / 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)
| Step | Detail |
|---|---|
| Parse header | Extract timestamp + signature |
| Reconstruct | timestamp + "." + raw body |
| HMAC compare | Constant-time |
| Reject stale | Within ±5 minutes |
| Reject duplicate | Track seen event IDs |
5. Implementing Retry Logic with Exponential Backoff
| Attempt | Delay |
|---|---|
| 1 | Immediate |
| 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
| Record | Detail |
|---|---|
| attempts | Status + response code each try |
| latency | For monitoring slow consumers |
| last status | Surfaced in subscriber UI |
| payload snapshot | For replay |
7. Implementing Webhook Failure Handling
| Policy | Detail |
|---|---|
| Auto-disable | After N consecutive failures (e.g., 24h) |
| Notify subscriber | Email on disable |
| Manual replay | UI button to retry |
| Health endpoint | Subscriber status page |
8. Implementing Webhook Event Filtering
| Filter | Detail |
|---|---|
| Event types | Subscribe to subset |
| Resource scope | Per project/tenant |
| Conditions | e.g., only orders > $100 |
| Field mask | Limit payload fields |
9. Implementing Webhook Replay
| Mechanism | Detail |
|---|---|
| Store raw event | Immutable for window (e.g., 30 days) |
| Replay endpoint | Resend by event ID or range |
| Idempotency key | Same event ID; consumer dedupes |
10. Implementing Webhook Security
| Practice | Detail |
|---|---|
| HTTPS only | Reject http:// URLs |
| Signature | HMAC required |
| Timestamp | Replay defense |
| SSRF guard | Block internal IPs / metadata endpoints |
| Allow-listed IPs | Publish source ranges for subscribers |
11. Implementing Webhook Rate Limiting
| Per | Detail |
|---|---|
| Endpoint | Cap per-URL deliveries/sec |
| Subscription | Limit per-subscription queue depth |
| Tenant | Fair share globally |
| Backpressure | Pause on subscriber 429s |
12. Implementing Webhook Logging
| Field | Detail |
|---|---|
| event id, type | Correlation |
| subscription id, url | Target |
| attempt #, status, latency | Per try |
| response excerpt | First N bytes for debugging |