Add SendGrid webhook event models and signature verification #29
Conversation
Introduces comprehensive models for SendGrid webhook event types, including delivery, engagement, and account status change events. Adds ECDSA signature verification for webhook security, updates Package.swift to include swift-crypto, and provides extensive documentation and tests for event parsing and verification.
Codecov Report❌ Patch coverage is Additional details and impacted files@@ Coverage Diff @@
## main #29 +/- ##
===========================================
- Coverage 86.86% 53.54% -33.32%
===========================================
Files 12 14 +2
Lines 274 861 +587
===========================================
+ Hits 238 461 +223
- Misses 36 400 +364
🚀 New features to boost your workflow:
|
|
So this basically only adds structs that a Vapor/Hummingbird server should decode and methods to verify their signature, right? |
I just noticed that I am missing the received case. I will fix this shortly along with the CRUD operations https://www.twilio.com/docs/sendgrid/api-reference/webhooks/create-an-event-webhook |
Introduces methods for managing SendGrid Event Webhooks (create, test, retrieve, update, delete, signature verification, public key retrieval) and Parse Webhook settings/statistics in SendGridClient. Also updates SendGridError to include url and id fields for improved error context, and fixes the base API URL to support new endpoints.
Introduces SendGridReceivedEvent to handle inbound email 'received' events, updates SendGridWebhookEvent and related enums for the new event type, and adds models for event webhook input, settings, signature verification, and parse webhook statistics. Also adds sgContentType to engagement events and improves documentation for uniqueArgs.
Added unit tests to verify decoding of SendGrid 'received' webhook events, including support for both Unix and ISO 8601 timestamps, additional fields, and v3_payload_details. Also updated existing test data to use generic test values for consistency.
Updated several public method signatures in SendGridClient to use multiline formatting for parameters, improving readability and consistency. Also adjusted body encoding and decoding calls to multiline style.
Changed the expected sgEventId value in the delivered event decoding test to 'test_delivered_event_id' for consistency or improved test clarity.
@fpseverino all the failing tests are related to the email validation API |
fpseverino
left a comment
fpseverino
left a comment
There was a problem hiding this comment.
A very well designed API, great work!
You tested it with real SendGrid API keys, right?
|
|
||
| ```swift | ||
| import SendGridKit | ||
| import NIO |
There was a problem hiding this comment.
This should be Vapor, right? The example uses Vapor APIs it seems
There was a problem hiding this comment.
Yes, I will look at the Vapor doc to update this example.
| } | ||
| ``` | ||
|
|
||
| ### Webhook Event Processing |
There was a problem hiding this comment.
Could you also add this excellent documentation as an article in the DocC catalog?
There was a problem hiding this comment.
I'll do so shortly.
| /// Delivery events: bounce, delivered, deferred, dropped, processed, blocked | ||
| public struct SendGridDeliveryEvent: Codable, Sendable { | ||
| /// ID of the unsubscribe group that includes the recipient's email address. | ||
| public let asmGroupId: Int? |
There was a problem hiding this comment.
Same thing here with all the properties that end with "Id"
There was a problem hiding this comment.
We need to split this file into smaller ones, you should create a subfolder (inside the "Models" one) called "Webhooks" or something like that
| /// - Parameters: | ||
| /// - input: The request body | ||
| /// - onbehalfOf: The on-behalf-of header allows you to make API calls from a parent account on behalf of the parent's Subusers or customer accounts. | ||
| public func createEventWebhook(_ input: EventWebhookInput, onbehalfOf: String? = nil) async throws -> WebhookSettingsResponse { |
There was a problem hiding this comment.
I think we should make a separate client, just like for the email validation API
There was a problem hiding this comment.
Fair enough! I will do that.
Yes! |
Co-authored-by: Francesco Paolo Severino <[email protected]>
Co-authored-by: Francesco Paolo Severino <[email protected]>
Co-authored-by: Francesco Paolo Severino <[email protected]>
Co-authored-by: Francesco Paolo Severino <[email protected]>
Co-authored-by: Francesco Paolo Severino <[email protected]>
2 participants
Introduces comprehensive models for SendGrid webhook event types, including delivery, engagement, and account status change events. Adds ECDSA signature verification for webhook security, updates Package.swift to include swift-crypto, and provides extensive documentation and tests for event parsing and verification.
Closes #28