Class EventDataObjectDeserializer


public class EventDataObjectDeserializer extends Object
Deserialization helper to get StripeObject and handle failure due to schema incompatibility between the data object and the model classes. Event data object by default corresponds to the schema at API version tied to your Stripe account at the event creation time. This event version is in Event.getApiVersion(). The model classes for deserialization, however, corresponds to a specific version pinned to this library Stripe.API_VERSION. Thus, only data object with same API versions is guaranteed to deserialize safely.

To avoid this problem of API version mismatch, create a new webhook endpoint `api_versions` corresponding to Stripe.API_VERSION. For more information, see API reference

In practice, each API version update only affects specific set of classes, so event data object for the unaffected classes can still be serialized successfully -- even when the API versions do not match. (Although it is considered unsafe by the API version comparison.) In that case, you can use deserializeUnsafe()

Old events from Event.retrieve(String) or Event.list(Map) will have immutable API versions on them, and there is currently no support for rendering it at different API versions. If you find failure from reading these events, consider defining your own custom EventDataObjectDeserializer.CompatibilityTransformer to transform the raw JSON to one with schema compatible with this current model classes.

En event integration from webhook may look like the example below. Assuming that you have the event api version matching this library, you should safely find deserialized object from the deserializer.

   Event event = Webhook.constructEvent(payload, sigHeader, secret);
   EventDataObjectDeserializer dataObjectDeserializer = event.getDataObjectDeserializer();
   if (dataObjectDeserializer.getObject().isPresent()) {
     StripeObject stripeObject = dataObjectDeserializer.getObject().get();
   } else {
     throw new IllegalStateException(
       String.format("Unable to deserialize event data object for %s", event));
  • Method Details

    • getObject

      public Optional<StripeObject> getObject()
      Gets an Optional of data event object, in favor of the deprecated EventData.getObject(). When the optional is present, the deserialized StripeObject preserves high data integrity because of correspondence between schema of the API response and the model class (the underlying concrete class for abstract StripeObject) schema. This is when Event.getApiVersion() matches Stripe.API_VERSION. Otherwise, the optional is empty.
      Optional of stripe object when deserialization is safe.
    • getRawJson

      public String getRawJson()
      Get raw JSON string for the data object. This is the same data available in EventDataObjectDeserializationException.getRawJson() upon deserialization failure.
      JSON string the event data object.
    • deserializeUnsafe

      public StripeObject deserializeUnsafe() throws EventDataObjectDeserializationException
      Force deserialize raw JSON to StripeObject. The deserialized data is not guaranteed to fully represent the JSON. For example, events of new API version having fields that are not captured by current model class will be lost. Similarly, events of old API version having fields that should be translated into the new fields, like field rename, will be lost.

      Upon deserialization failure, consider making the JSON compatible to the current model classes and recover from failure with deserializeUnsafeWith(CompatibilityTransformer).

      Object with no guarantee on full representation of its original raw JSON response.
      EventDataObjectDeserializationException - exception that contains the message error and the raw JSON response of the StripeObject to be deserialized.
    • deserializeUnsafeWith

      public StripeObject deserializeUnsafeWith(EventDataObjectDeserializer.CompatibilityTransformer transformer)
      Deserialize JSON that has been processed by EventDataObjectDeserializer.CompatibilityTransformer.transform(JsonObject, String, String) into StripeObject. This deserialization method should only be used to handle events with schema incompatible to model class schema of this library. Throws JsonParseException when the transformed JSON remains incompatible with the model classes.
      deserialized StripeObject from user-supplied compatible JSON.
    • equals

      public boolean equals(Object o)
      equals in class Object
    • canEqual

      protected boolean canEqual(Object other)
    • hashCode

      public int hashCode()
      hashCode in class Object