Changes from gocardless/client-library-templates

README.md

@@ -226,6 +226,20 @@ public class WebhookHandler {
 }
 ```
 
+#### Accessing the webhook ID
+
+If you need to access the webhook ID for debugging purposes, you can use `Webhook.parseWithMeta` instead:
+
+```java
+import com.gocardless.http.WebhookParseResult;
+
+WebhookParseResult result = Webhook.parseWithMeta(requestBody, signatureHeader, webhookEndpointSecret);
+List<Event> events = result.getEvents();
+String webhookId = result.getWebhookId(); // e.g. "WB123" - useful for debugging
+```
+
+Note: The webhook ID is intended for debugging and logging purposes only. It should not be used for deduplication - instead, use the event IDs to deduplicate, as each event has a unique ID that remains consistent if the same event is sent multiple times.
+
 For more details on working with webhooks, see our ["Getting started" guide](https://developer.gocardless.com/getting-started/api/introduction/?lang=java).
 
 ## Upgrading from older versions

src/main/java/com/gocardless/Webhook.java

@@ -1,6 +1,7 @@
 package com.gocardless;
 
 import com.gocardless.errors.InvalidSignatureException;
+import com.gocardless.http.WebhookParseResult;
 import com.gocardless.http.WebhookParser;
 import com.gocardless.resources.Event;
 import java.security.MessageDigest;
@@ -38,6 +39,30 @@ public static List<Event> parse(String requestBody, String signatureHeader,
         }
     }
 
+    /**
+     * Validates that a webhook was genuinely sent by GoCardless using `isValidSignature`, and then
+     * parses it into a `WebhookParseResult` containing both the events and the webhook ID from the
+     * meta field.
+     *
+     * @param requestBody the request body
+     * @param signatureHeader the signature included in the request, found in the
+     *        `Webhook-Signature` header
+     * @param webhookEndpointSecret the webhook endpoint secret for your webhook endpoint, as
+     *        configured in your GoCardless Dashboard
+     * @return a WebhookParseResult containing the events and webhook ID
+     * @throws com.gocardless.errors.InvalidSignatureException if the signature header specified
+     *         does not match the signature computed using the request body and webhook endpoint
+     *         secret
+     */
+    public static WebhookParseResult parseWithMeta(String requestBody, String signatureHeader,
+            String webhookEndpointSecret) {
+        if (isValidSignature(requestBody, signatureHeader, webhookEndpointSecret)) {
+            return WebhookParser.parseWithMeta(requestBody);
+        } else {
+            throw new InvalidSignatureException();
+        }
+    }
+
     /**
      * Validates that a webhook was genuinely sent by GoCardless by computing its signature using
      * the body and your webhook endpoint secret, and comparing that with the signature included in

src/main/java/com/gocardless/http/WebhookParseResult.java

@@ -0,0 +1,31 @@
+package com.gocardless.http;
+
+import com.gocardless.resources.Event;
+import com.google.common.collect.ImmutableList;
+
+/**
+ * Represents the result of parsing a webhook, containing both the events and the webhook metadata.
+ */
+public final class WebhookParseResult {
+    private final ImmutableList<Event> events;
+    private final String webhookId;
+
+    WebhookParseResult(ImmutableList<Event> events, String webhookId) {
+        this.events = events;
+        this.webhookId = webhookId;
+    }
+
+    /**
+     * Returns the list of events included in the webhook.
+     */
+    public ImmutableList<Event> getEvents() {
+        return events;
+    }
+
+    /**
+     * Returns the webhook ID from the meta field, or null if not present.
+     */
+    public String getWebhookId() {
+        return webhookId;
+    }
+}

src/main/java/com/gocardless/http/WebhookParser.java

@@ -15,4 +15,22 @@ public static ImmutableList<Event> parse(String responseBody) {
         return responseParser.parseMultiple(responseBody, "events",
                 new TypeToken<List<Event>>() {});
     }
+
+    public static WebhookParseResult parseWithMeta(String responseBody) {
+        Gson gson = GsonFactory.build();
+        ResponseParser responseParser = new ResponseParser(gson);
+        ImmutableList<Event> events = responseParser.parseMultiple(responseBody, "events",
+                new TypeToken<List<Event>>() {});
+        String webhookId = null;
+        try {
+            JsonObject json = new JsonParser().parse(responseBody).getAsJsonObject();
+            JsonObject meta = json.getAsJsonObject("meta");
+            if (meta != null && meta.has("webhook_id")) {
+                webhookId = meta.get("webhook_id").getAsString();
+            }
+        } catch (JsonSyntaxException | IllegalStateException e) {
+            // If we can't parse meta, just leave webhookId as null
+        }
+        return new WebhookParseResult(events, webhookId);
+    }
 }

src/main/java/com/gocardless/resources/Balance.java

@@ -49,7 +49,7 @@ public BalanceType getBalanceType() {
     }
 
     /**
-     * [ISO 4217](http://en.wikipedia.org/wiki/ISO_4217#Active_codes) currency code. Currently
+     * [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217#Active_codes) currency code. Currently
      * "AUD", "CAD", "DKK", "EUR", "GBP", "NZD", "SEK" and "USD" are supported.
      */
     public Currency getCurrency() {

src/main/java/com/gocardless/resources/BillingRequest.java

@@ -495,7 +495,7 @@ public Integer getAppFee() {
         }
 
         /**
-         * [ISO 4217](http://en.wikipedia.org/wiki/ISO_4217#Active_codes) currency code. Currently
+         * [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217#Active_codes) currency code. Currently
          * "USD" and "CAD" are supported.
          */
         public String getCurrency() {
@@ -894,7 +894,7 @@ public Constraints getConstraints() {
         }
 
         /**
-         * [ISO 4217](http://en.wikipedia.org/wiki/ISO_4217#Active_codes) currency code.
+         * [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217#Active_codes) currency code.
          */
         public String getCurrency() {
             return currency;
@@ -1110,8 +1110,9 @@ public Alignment getAlignment() {
                 }
 
                 /**
-                 * (Optional) The maximum number of payments that can be collected in this periodic
-                 * limit.
+                 * The maximum number of payments that can be collected in this periodic limit.
+                 * _Note:_ This is only supported for the PayTo scheme, where it is required.
+                 * 
                  */
                 public Integer getMaxPayments() {
                     return maxPayments;
@@ -1213,7 +1214,7 @@ public Integer getAppFee() {
         }
 
         /**
-         * [ISO 4217](http://en.wikipedia.org/wiki/ISO_4217#Active_codes) currency code. `GBP` and
+         * [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217#Active_codes) currency code. `GBP` and
          * `EUR` supported; `GBP` with your customers in the UK and for `EUR` with your customers in
          * supported Eurozone countries only.
          */
@@ -1407,7 +1408,7 @@ public String getId() {
             }
 
             /**
-             * [ISO 639-1](http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) code. Used as the
+             * [ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) code. Used as the
              * language for notification emails sent by GoCardless if your organisation does not
              * send its own (see [compliance requirements](#appendix-compliance-requirements)).
              * Currently only "en", "fr", "de", "pt", "es", "it", "nl", "da", "nb", "sl", "sv" are
@@ -1503,7 +1504,7 @@ public String getBankName() {
 
             /**
              * [ISO 3166-1 alpha-2
-             * code](http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements).
+             * code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements).
              * Defaults to the country code of the `iban` if supplied, otherwise is required.
              */
             public String getCountryCode() {
@@ -1519,7 +1520,7 @@ public String getCreatedAt() {
             }
 
             /**
-             * [ISO 4217](http://en.wikipedia.org/wiki/ISO_4217#Active_codes) currency code.
+             * [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217#Active_codes) currency code.
              * Currently "AUD", "CAD", "DKK", "EUR", "GBP", "NZD", "SEK" and "USD" are supported.
              */
             public String getCurrency() {
@@ -1634,7 +1635,7 @@ public String getCity() {
 
             /**
              * [ISO 3166-1 alpha-2
-             * code.](http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements)
+             * code.](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements)
              */
             public String getCountryCode() {
                 return countryCode;
@@ -1760,7 +1761,7 @@ public Integer getCount() {
         }
 
         /**
-         * [ISO 4217](http://en.wikipedia.org/wiki/ISO_4217#Active_codes) currency code. Currently
+         * [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217#Active_codes) currency code. Currently
          * "USD" and "CAD" are supported.
          */
         public String getCurrency() {

src/main/java/com/gocardless/resources/BillingRequestFlow.java

@@ -309,7 +309,7 @@ public String getCompanyName() {
 
         /**
          * [ISO 3166-1 alpha-2
-         * code.](http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements)
+         * code.](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements)
          */
         public String getCountryCode() {
             return countryCode;

src/main/java/com/gocardless/resources/BillingRequestTemplate.java

@@ -73,7 +73,7 @@ public MandateRequestConstraints getMandateRequestConstraints() {
     }
 
     /**
-     * [ISO 4217](http://en.wikipedia.org/wiki/ISO_4217#Active_codes) currency code.
+     * [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217#Active_codes) currency code.
      */
     public String getMandateRequestCurrency() {
         return mandateRequestCurrency;
@@ -158,9 +158,9 @@ public String getPaymentRequestAmount() {
     }
 
     /**
-     * [ISO 4217](http://en.wikipedia.org/wiki/ISO_4217#Active_codes) currency code. `GBP` and `EUR`
-     * supported; `GBP` with your customers in the UK and for `EUR` with your customers in supported
-     * Eurozone countries only.
+     * [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217#Active_codes) currency code. `GBP` and
+     * `EUR` supported; `GBP` with your customers in the UK and for `EUR` with your customers in
+     * supported Eurozone countries only.
      */
     public String getPaymentRequestCurrency() {
         return paymentRequestCurrency;
@@ -313,8 +313,9 @@ public Alignment getAlignment() {
             }
 
             /**
-             * (Optional) The maximum number of payments that can be collected in this periodic
-             * limit.
+             * The maximum number of payments that can be collected in this periodic limit. _Note:_
+             * This is only supported for the PayTo scheme, where it is required.
+             * 
              */
             public Integer getMaxPayments() {
                 return maxPayments;

src/main/java/com/gocardless/resources/BillingRequestWithAction.java

@@ -697,7 +697,7 @@ public Integer getAppFee() {
             }
 
             /**
-             * [ISO 4217](http://en.wikipedia.org/wiki/ISO_4217#Active_codes) currency code.
+             * [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217#Active_codes) currency code.
              * Currently "USD" and "CAD" are supported.
              */
             public String getCurrency() {
@@ -1098,7 +1098,7 @@ public Constraints getConstraints() {
             }
 
             /**
-             * [ISO 4217](http://en.wikipedia.org/wiki/ISO_4217#Active_codes) currency code.
+             * [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217#Active_codes) currency code.
              */
             public String getCurrency() {
                 return currency;
@@ -1319,8 +1319,9 @@ public Alignment getAlignment() {
                     }
 
                     /**
-                     * (Optional) The maximum number of payments that can be collected in this
-                     * periodic limit.
+                     * The maximum number of payments that can be collected in this periodic limit.
+                     * _Note:_ This is only supported for the PayTo scheme, where it is required.
+                     * 
                      */
                     public Integer getMaxPayments() {
                         return maxPayments;
@@ -1422,7 +1423,7 @@ public Integer getAppFee() {
             }
 
             /**
-             * [ISO 4217](http://en.wikipedia.org/wiki/ISO_4217#Active_codes) currency code. `GBP`
+             * [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217#Active_codes) currency code. `GBP`
              * and `EUR` supported; `GBP` with your customers in the UK and for `EUR` with your
              * customers in supported Eurozone countries only.
              */
@@ -1617,7 +1618,7 @@ public String getId() {
                 }
 
                 /**
-                 * [ISO 639-1](http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) code. Used as
+                 * [ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) code. Used as
                  * the language for notification emails sent by GoCardless if your organisation does
                  * not send its own (see [compliance
                  * requirements](#appendix-compliance-requirements)). Currently only "en", "fr",
@@ -1714,7 +1715,7 @@ public String getBankName() {
 
                 /**
                  * [ISO 3166-1 alpha-2
-                 * code](http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements).
+                 * code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements).
                  * Defaults to the country code of the `iban` if supplied, otherwise is required.
                  */
                 public String getCountryCode() {
@@ -1730,7 +1731,7 @@ public String getCreatedAt() {
                 }
 
                 /**
-                 * [ISO 4217](http://en.wikipedia.org/wiki/ISO_4217#Active_codes) currency code.
+                 * [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217#Active_codes) currency code.
                  * Currently "AUD", "CAD", "DKK", "EUR", "GBP", "NZD", "SEK" and "USD" are
                  * supported.
                  */
@@ -1846,7 +1847,7 @@ public String getCity() {
 
                 /**
                  * [ISO 3166-1 alpha-2
-                 * code.](http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements)
+                 * code.](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements)
                  */
                 public String getCountryCode() {
                     return countryCode;
@@ -1973,7 +1974,7 @@ public Integer getCount() {
             }
 
             /**
-             * [ISO 4217](http://en.wikipedia.org/wiki/ISO_4217#Active_codes) currency code.
+             * [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217#Active_codes) currency code.
              * Currently "USD" and "CAD" are supported.
              */
             public String getCurrency() {

src/main/java/com/gocardless/resources/Creditor.java

@@ -89,7 +89,7 @@ public String getCity() {
 
     /**
      * [ISO 3166-1 alpha-2
-     * code.](http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements)
+     * code.](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements)
      */
     public String getCountryCode() {
         return countryCode;
@@ -119,10 +119,10 @@ public Boolean getCustomPaymentPagesEnabled() {
     }
 
     /**
-     * [ISO 4217](http://en.wikipedia.org/wiki/ISO_4217#Active_codes) code for the currency in which
-     * amounts will be paid out (after foreign exchange). Currently "AUD", "CAD", "DKK", "EUR",
-     * "GBP", "NZD", "SEK" and "USD" are supported. Present only if payouts will be (or were) made
-     * via foreign exchange.
+     * [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217#Active_codes) code for the currency in
+     * which amounts will be paid out (after foreign exchange). Currently "AUD", "CAD", "DKK",
+     * "EUR", "GBP", "NZD", "SEK" and "USD" are supported. Present only if payouts will be (or were)
+     * made via foreign exchange.
      */
     public FxPayoutCurrency getFxPayoutCurrency() {
         return fxPayoutCurrency;
@@ -396,7 +396,7 @@ public String getCity() {
 
         /**
          * [ISO 3166-1 alpha-2
-         * code.](http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements)
+         * code.](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements)
          */
         public String getCountryCode() {
             return countryCode;

src/main/java/com/gocardless/resources/CreditorBankAccount.java

@@ -71,7 +71,7 @@ public String getBankName() {
 
     /**
      * [ISO 3166-1 alpha-2
-     * code](http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements).
+     * code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements).
      * Defaults to the country code of the `iban` if supplied, otherwise is required.
      */
     public String getCountryCode() {
@@ -86,7 +86,7 @@ public String getCreatedAt() {
     }
 
     /**
-     * [ISO 4217](http://en.wikipedia.org/wiki/ISO_4217#Active_codes) currency code. Currently
+     * [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217#Active_codes) currency code. Currently
      * "AUD", "CAD", "DKK", "EUR", "GBP", "NZD", "SEK" and "USD" are supported.
      */
     public String getCurrency() {