Repository navigation
Expand file tree
/
Copy pathwebhooks.py
More file actions
326 lines (267 loc) · 9.29 KB
/
Copy pathwebhooks.py
File metadata and controls
326 lines (267 loc) · 9.29 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
"""Webhook verification and event construction for ByteSend webhooks.
This module provides secure webhook signature verification using HMAC-SHA256,
timestamp validation, and type-safe event parsing.
"""
from __future__ import annotations
import hashlib
import hmac
import json
import time
from typing import Any, Dict, Literal, Mapping, Optional, Union
from .types import WebhookEventData
# Webhook header names
WEBHOOK_SIGNATURE_HEADER = "X-ByteSend-Signature"
WEBHOOK_TIMESTAMP_HEADER = "X-ByteSend-Timestamp"
WEBHOOK_EVENT_HEADER = "X-ByteSend-Event"
WEBHOOK_CALL_HEADER = "X-ByteSend-Call"
# Signature format
SIGNATURE_PREFIX = "v1="
# Default tolerance: 5 minutes in milliseconds
DEFAULT_TOLERANCE_MS = 5 * 60 * 1000
WebhookVerificationErrorCode = Literal[
"MISSING_SIGNATURE",
"MISSING_TIMESTAMP",
"INVALID_SIGNATURE_FORMAT",
"INVALID_TIMESTAMP",
"TIMESTAMP_OUT_OF_RANGE",
"SIGNATURE_MISMATCH",
"INVALID_BODY",
"INVALID_JSON",
]
class WebhookVerificationError(Exception):
"""Error raised when webhook verification fails.
Attributes:
code: The error code indicating the type of verification failure.
message: A human-readable description of the error.
"""
def __init__(self, code: WebhookVerificationErrorCode, message: str) -> None:
self.code = code
self.message = message
super().__init__(message)
def __str__(self) -> str:
return f"[{self.code}] {self.message}"
class Webhooks:
"""Webhook verification and event construction.
This class provides methods to verify webhook signatures and parse
webhook events with type safety.
Parameters
----------
secret:
The webhook signing secret (starts with 'whsec_').
Example
-------
```python
from bytesend import ByteSend
bytesend = ByteSend("us_12345")
webhooks = bytesend.webhooks("whsec_xxx")
# Flask example
@app.route("/webhook", methods=["POST"])
def handle_webhook():
try:
event = webhooks.construct_event(
request.data,
headers=request.headers
)
if event["type"] == "email.delivered":
print(f"Email delivered to {event['data']['to']}")
return "OK", 200
except WebhookVerificationError as e:
return str(e), 400
```
"""
def __init__(self, secret: str) -> None:
self._secret = secret
def verify(
self,
body: Union[str, bytes],
*,
headers: Mapping[str, Any],
secret: Optional[str] = None,
tolerance: Optional[int] = None,
) -> bool:
"""Verify webhook signature without parsing the event.
Parameters
----------
body:
Raw webhook body (string or bytes).
headers:
Request headers (dict-like object).
secret:
Optional override for the webhook secret.
tolerance:
Optional tolerance in milliseconds for timestamp validation.
Defaults to 5 minutes. Set to -1 to disable timestamp validation.
Returns
-------
bool
True if signature is valid, False otherwise.
Example
-------
```python
is_valid = webhooks.verify(body, headers=request.headers)
if not is_valid:
return "Invalid signature", 401
```
"""
try:
self._verify_internal(body, headers=headers, secret=secret, tolerance=tolerance)
return True
except WebhookVerificationError:
return False
def construct_event(
self,
body: Union[str, bytes],
*,
headers: Mapping[str, Any],
secret: Optional[str] = None,
tolerance: Optional[int] = None,
) -> WebhookEventData:
"""Verify and parse a webhook event.
Parameters
----------
body:
Raw webhook body (string or bytes).
headers:
Request headers (dict-like object).
secret:
Optional override for the webhook secret.
tolerance:
Optional tolerance in milliseconds for timestamp validation.
Defaults to 5 minutes. Set to -1 to disable timestamp validation.
Returns
-------
WebhookEventData
Verified and typed webhook event.
Raises
------
WebhookVerificationError
If the webhook signature is invalid or the payload cannot be parsed.
Example
-------
```python
# Flask
event = webhooks.construct_event(
request.data,
headers=request.headers
)
# Django
event = webhooks.construct_event(
request.body,
headers=request.headers
)
# FastAPI
event = webhooks.construct_event(
await request.body(),
headers=dict(request.headers)
)
# Type-safe event handling
if event["type"] == "email.delivered":
print(event["data"]["to"])
elif event["type"] == "email.bounced":
print(event["data"]["bounce"]["type"])
```
"""
self._verify_internal(body, headers=headers, secret=secret, tolerance=tolerance)
body_string = _to_string(body)
try:
return json.loads(body_string)
except (json.JSONDecodeError, ValueError) as e:
raise WebhookVerificationError(
"INVALID_JSON",
f"Webhook payload is not valid JSON: {e}",
) from e
def _verify_internal(
self,
body: Union[str, bytes],
*,
headers: Mapping[str, Any],
secret: Optional[str] = None,
tolerance: Optional[int] = None,
) -> None:
"""Internal verification logic."""
webhook_secret = secret if secret is not None else self._secret
signature = _get_header(headers, WEBHOOK_SIGNATURE_HEADER)
timestamp = _get_header(headers, WEBHOOK_TIMESTAMP_HEADER)
if not signature:
raise WebhookVerificationError(
"MISSING_SIGNATURE",
f"Missing {WEBHOOK_SIGNATURE_HEADER} header",
)
if not timestamp:
raise WebhookVerificationError(
"MISSING_TIMESTAMP",
f"Missing {WEBHOOK_TIMESTAMP_HEADER} header",
)
if not signature.startswith(SIGNATURE_PREFIX):
raise WebhookVerificationError(
"INVALID_SIGNATURE_FORMAT",
"Signature header must start with v1=",
)
try:
timestamp_num = int(timestamp)
except ValueError as e:
raise WebhookVerificationError(
"INVALID_TIMESTAMP",
"Timestamp header must be a number (milliseconds since epoch)",
) from e
tolerance_ms = tolerance if tolerance is not None else DEFAULT_TOLERANCE_MS
now = int(time.time() * 1000)
if tolerance_ms >= 0 and abs(now - timestamp_num) > tolerance_ms:
raise WebhookVerificationError(
"TIMESTAMP_OUT_OF_RANGE",
"Webhook timestamp is outside the allowed tolerance",
)
body_string = _to_string(body)
expected = _compute_signature(webhook_secret, timestamp, body_string)
if not _safe_compare(expected, signature):
raise WebhookVerificationError(
"SIGNATURE_MISMATCH",
"Webhook signature does not match",
)
def _compute_signature(secret: str, timestamp: str, body: str) -> str:
"""Compute the HMAC-SHA256 signature for webhook verification."""
message = f"{timestamp}.{body}"
signature = hmac.new(
secret.encode("utf-8"),
message.encode("utf-8"),
hashlib.sha256,
).hexdigest()
return f"{SIGNATURE_PREFIX}{signature}"
def _to_string(body: Union[str, bytes]) -> str:
"""Convert body to UTF-8 string."""
if isinstance(body, str):
return body
if isinstance(body, bytes):
try:
return body.decode("utf-8")
except UnicodeDecodeError as e:
raise WebhookVerificationError(
"INVALID_BODY",
"Webhook body must be valid UTF-8.",
) from e
raise WebhookVerificationError(
"INVALID_BODY",
f"Unsupported body type: {type(body).__name__}. Expected str or bytes.",
)
def _get_header(headers: Mapping[str, Any], name: str) -> Optional[str]:
"""Get header value in a case-insensitive manner."""
if headers is None:
return None
# Try direct access first
if name in headers:
value = headers[name]
if isinstance(value, list):
return value[0] if value else None
return str(value) if value is not None else None
# Case-insensitive lookup
lower_name = name.lower()
for key in headers:
if key.lower() == lower_name:
value = headers[key]
if isinstance(value, list):
return value[0] if value else None
return str(value) if value is not None else None
return None
def _safe_compare(a: str, b: str) -> bool:
"""Timing-safe string comparison to prevent timing attacks."""
return hmac.compare_digest(a.encode("utf-8"), b.encode("utf-8"))