feat(sdk): webhooks

README.md

@@ -19,7 +19,7 @@ The .NET SDK for the SumUp [API](https://developer.sumup.com).
 dotnet add package SumUp --prerelease
 ```
 
-See `examples/Basic`, `examples/CardReaderCheckout`, and `examples/OAuth2` for runnable projects.
+See `examples/Basic`, `examples/CardReaderCheckout`, `examples/OAuth2`, and `examples/Webhooks` for runnable projects.
 
 ## Supported .NET Versions
 
@@ -104,11 +104,32 @@ var readerCheckout = await client.Readers.CreateCheckoutAsync(
 Console.WriteLine($"Reader checkout created: {readerCheckout.Data?.Data?.ClientTransactionId}");
 ```
 
+### Handling Webhooks
+
+```csharp
+using SumUp;
+
+using var client = new SumUpClient();
+var webhookHandler = client.CreateWebhookHandler(secret: "whsec_...");
+
+var eventNotification = webhookHandler.VerifyAndParse(
+    signatureHeader: request.Headers[WebhookConstants.SignatureHeader].ToString(),
+    timestampHeader: request.Headers[WebhookConstants.TimestampHeader].ToString(),
+    body: rawRequestBody);
+
+if (eventNotification is CheckoutCreatedEvent checkoutCreated)
+{
+    var checkout = await checkoutCreated.FetchObjectAsync();
+    Console.WriteLine($"Received checkout {checkout?.Id}");
+}
+```
+
 ## Examples
 
 - `examples/Basic` – lists recent checkouts to sanity check your API token.
 - `examples/CardReaderCheckout` – mirrors the `../sumup-rs/examples/card_reader_checkout.rs` sample by listing the merchant’s paired readers and creating a €10 checkout on the first available device.
 - `examples/OAuth2` – starts a local OAuth2 Authorization Code flow with PKCE, exchanges the callback code for an access token, and fetches merchant information using the returned `merchant_code`.
+- `examples/Webhooks` – runs a minimal ASP.NET Core endpoint that verifies `X-SumUp-Webhook-*` headers, parses typed webhook events, and fetches the referenced object through the SDK.
 
 To run the card reader example:
 
@@ -129,4 +150,12 @@ export REDIRECT_URI="http://localhost:8080/callback"
 dotnet run --project examples/OAuth2
 ```
 
+To run the webhook example:
+
+```sh
+export SUMUP_ACCESS_TOKEN="your_api_key"
+export SUMUP_WEBHOOK_SECRET="whsec_..."
+dotnet run --project examples/Webhooks
+```
+
 [docs-badge]: https://img.shields.io/badge/SumUp-documentation-white.svg?logo=data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMjQiIGhlaWdodD0iMjQiIHZpZXdCb3g9IjAgMCAyNCAyNCIgZmlsbD0ibm9uZSIgY29sb3I9IndoaXRlIiB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciPgogICAgPHBhdGggZD0iTTIyLjI5IDBIMS43Qy43NyAwIDAgLjc3IDAgMS43MVYyMi4zYzAgLjkzLjc3IDEuNyAxLjcxIDEuN0gyMi4zYy45NCAwIDEuNzEtLjc3IDEuNzEtMS43MVYxLjdDMjQgLjc3IDIzLjIzIDAgMjIuMjkgMFptLTcuMjIgMTguMDdhNS42MiA1LjYyIDAgMCAxLTcuNjguMjQuMzYuMzYgMCAwIDEtLjAxLS40OWw3LjQ0LTcuNDRhLjM1LjM1IDAgMCAxIC40OSAwIDUuNiA1LjYgMCAwIDEtLjI0IDcuNjlabTEuNTUtMTEuOS03LjQ0IDcuNDVhLjM1LjM1IDAgMCAxLS41IDAgNS42MSA1LjYxIDAgMCAxIDcuOS03Ljk2bC4wMy4wM2MuMTMuMTMuMTQuMzUuMDEuNDlaIiBmaWxsPSJjdXJyZW50Q29sb3IiLz4KPC9zdmc+

SumUp.sln

@@ -15,6 +15,8 @@ Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Basic", "examples\Basic\Bas
 EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "CardReaderCheckout", "examples\CardReaderCheckout\CardReaderCheckout.csproj", "{5DD2877F-E30C-42F1-9192-4E80DB983FA8}"
 EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Webhooks", "examples\Webhooks\Webhooks.csproj", "{50E0145D-2C1B-4C9D-B408-DB2C160F1E71}"
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU
@@ -40,11 +42,16 @@ Global
 		{5DD2877F-E30C-42F1-9192-4E80DB983FA8}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{5DD2877F-E30C-42F1-9192-4E80DB983FA8}.Release|Any CPU.ActiveCfg = Release|Any CPU
 		{5DD2877F-E30C-42F1-9192-4E80DB983FA8}.Release|Any CPU.Build.0 = Release|Any CPU
+		{50E0145D-2C1B-4C9D-B408-DB2C160F1E71}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{50E0145D-2C1B-4C9D-B408-DB2C160F1E71}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{50E0145D-2C1B-4C9D-B408-DB2C160F1E71}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{50E0145D-2C1B-4C9D-B408-DB2C160F1E71}.Release|Any CPU.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(NestedProjects) = preSolution
 		{8E9FAE0B-D427-4A36-B173-8F5EAB93B47F} = {00434BF0-6DBC-4D10-A4E1-CCCE5AAFFCC0}
 		{C3EB3DA3-79E1-483E-A838-CF8A563BF0CB} = {00434BF0-6DBC-4D10-A4E1-CCCE5AAFFCC0}
 		{38032149-4A67-4856-8854-00F400CBA388} = {27A079ED-6B3F-4A5D-BC98-647A379F5864}
 		{5DD2877F-E30C-42F1-9192-4E80DB983FA8} = {27A079ED-6B3F-4A5D-BC98-647A379F5864}
+		{50E0145D-2C1B-4C9D-B408-DB2C160F1E71} = {27A079ED-6B3F-4A5D-BC98-647A379F5864}
 EndGlobalSection
 EndGlobal

examples/Webhooks/Program.cs

@@ -0,0 +1,62 @@
+using System.Text;
+using SumUp;
+
+var builder = WebApplication.CreateBuilder(args);
+
+builder.Services.AddSingleton<SumUpClient>(_ => new SumUpClient());
+
+var app = builder.Build();
+
+app.MapPost("/webhooks/sumup", async (HttpRequest request, SumUpClient client) =>
+{
+    using var reader = new StreamReader(request.Body, Encoding.UTF8);
+    var body = await reader.ReadToEndAsync();
+
+    try
+    {
+        var webhookHandler = client.CreateWebhookHandler();
+        var eventNotification = webhookHandler.VerifyAndParse(
+            request.Headers[WebhookConstants.SignatureHeader].ToString(),
+            request.Headers[WebhookConstants.TimestampHeader].ToString(),
+            body);
+
+        switch (eventNotification)
+        {
+            case CheckoutCreatedEvent checkoutCreated:
+                {
+                    var checkout = await checkoutCreated.FetchObjectAsync();
+                    Console.WriteLine($"Received checkout.created for checkout {checkout?.Id}");
+                    break;
+                }
+            case CheckoutProcessedEvent checkoutProcessed:
+                {
+                    var checkout = await checkoutProcessed.FetchObjectAsync();
+                    Console.WriteLine($"Received checkout.processed for checkout {checkout?.Id}");
+                    break;
+                }
+            case MemberCreatedEvent memberCreated:
+                {
+                    var member = await memberCreated.FetchObjectAsync();
+                    Console.WriteLine($"Received member.created for member {member?.Id}");
+                    break;
+                }
+            default:
+                Console.WriteLine($"Received webhook {eventNotification.Type} for object {eventNotification.Object.Id}");
+                break;
+        }
+
+        return Results.Ok();
+    }
+    catch (WebhookException exception)
+    {
+        Console.Error.WriteLine($"Webhook verification failed: {exception.Message}");
+        return Results.BadRequest(new { error = exception.Message });
+    }
+});
+
+app.MapGet("/", () => Results.Text("POST SumUp webhooks to /webhooks/sumup"));
+
+Console.WriteLine("Listening on http://localhost:5000");
+Console.WriteLine($"Set {WebhookConstants.SecretEnvironmentVariable} and SUMUP_ACCESS_TOKEN before sending live webhooks.");
+
+await app.RunAsync("http://localhost:5000");

examples/Webhooks/Webhooks.csproj

@@ -0,0 +1,13 @@
+<Project Sdk="Microsoft.NET.Sdk.Web">
+
+  <PropertyGroup>
+    <TargetFramework>net8.0</TargetFramework>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\src\SumUp\SumUp.csproj" />
+  </ItemGroup>
+
+</Project>