Webhook.java

// Code generated by GetStream internal OpenAPI code generator. DO NOT EDIT.

package io.getstream;

import com.fasterxml.jackson.core.JsonProcessingException;
import com.fasterxml.jackson.databind.DeserializationFeature;
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import io.getstream.exceptions.StreamException;
import io.getstream.models.ActivityAddedEvent;
import io.getstream.models.ActivityDeletedEvent;
import io.getstream.models.ActivityFeedbackEvent;
import io.getstream.models.ActivityMarkEvent;
import io.getstream.models.ActivityPinnedEvent;
import io.getstream.models.ActivityReactionAddedEvent;
import io.getstream.models.ActivityReactionDeletedEvent;
import io.getstream.models.ActivityReactionUpdatedEvent;
import io.getstream.models.ActivityRemovedFromFeedEvent;
import io.getstream.models.ActivityRestoredEvent;
import io.getstream.models.ActivityUnpinnedEvent;
import io.getstream.models.ActivityUpdatedEvent;
import io.getstream.models.AppealAcceptedEvent;
import io.getstream.models.AppealCreatedEvent;
import io.getstream.models.AppealRejectedEvent;
import io.getstream.models.AsyncBulkImageModerationEvent;
import io.getstream.models.AsyncExportChannelsEvent;
import io.getstream.models.AsyncExportErrorEvent;
import io.getstream.models.AsyncExportModerationLogsEvent;
import io.getstream.models.AsyncExportReviewQueueEvent;
import io.getstream.models.AsyncExportUsersEvent;
import io.getstream.models.AsyncImportErrorEvent;
import io.getstream.models.AsyncImportSuccessEvent;
import io.getstream.models.BlockedUserEvent;
import io.getstream.models.BookmarkAddedEvent;
import io.getstream.models.BookmarkDeletedEvent;
import io.getstream.models.BookmarkFolderDeletedEvent;
import io.getstream.models.BookmarkFolderUpdatedEvent;
import io.getstream.models.BookmarkUpdatedEvent;
import io.getstream.models.CallAcceptedEvent;
import io.getstream.models.CallClosedCaptionsFailedEvent;
import io.getstream.models.CallClosedCaptionsStartedEvent;
import io.getstream.models.CallClosedCaptionsStoppedEvent;
import io.getstream.models.CallCreatedEvent;
import io.getstream.models.CallDTMFEvent;
import io.getstream.models.CallDeletedEvent;
import io.getstream.models.CallEndedEvent;
import io.getstream.models.CallFrameRecordingFailedEvent;
import io.getstream.models.CallFrameRecordingFrameReadyEvent;
import io.getstream.models.CallFrameRecordingStartedEvent;
import io.getstream.models.CallFrameRecordingStoppedEvent;
import io.getstream.models.CallHLSBroadcastingFailedEvent;
import io.getstream.models.CallHLSBroadcastingStartedEvent;
import io.getstream.models.CallHLSBroadcastingStoppedEvent;
import io.getstream.models.CallLiveStartedEvent;
import io.getstream.models.CallMemberAddedEvent;
import io.getstream.models.CallMemberRemovedEvent;
import io.getstream.models.CallMemberUpdatedEvent;
import io.getstream.models.CallMemberUpdatedPermissionEvent;
import io.getstream.models.CallMissedEvent;
import io.getstream.models.CallModerationBlurEvent;
import io.getstream.models.CallModerationWarningEvent;
import io.getstream.models.CallNotificationEvent;
import io.getstream.models.CallReactionEvent;
import io.getstream.models.CallRecordingFailedEvent;
import io.getstream.models.CallRecordingReadyEvent;
import io.getstream.models.CallRecordingStartedEvent;
import io.getstream.models.CallRecordingStoppedEvent;
import io.getstream.models.CallRejectedEvent;
import io.getstream.models.CallRingEvent;
import io.getstream.models.CallRtmpBroadcastFailedEvent;
import io.getstream.models.CallRtmpBroadcastStartedEvent;
import io.getstream.models.CallRtmpBroadcastStoppedEvent;
import io.getstream.models.CallSessionEndedEvent;
import io.getstream.models.CallSessionParticipantCountsUpdatedEvent;
import io.getstream.models.CallSessionParticipantJoinedEvent;
import io.getstream.models.CallSessionParticipantLeftEvent;
import io.getstream.models.CallSessionStartedEvent;
import io.getstream.models.CallStatsReportReadyEvent;
import io.getstream.models.CallTranscriptionFailedEvent;
import io.getstream.models.CallTranscriptionReadyEvent;
import io.getstream.models.CallTranscriptionStartedEvent;
import io.getstream.models.CallTranscriptionStoppedEvent;
import io.getstream.models.CallUpdatedEvent;
import io.getstream.models.CallUserFeedbackSubmittedEvent;
import io.getstream.models.CallUserMutedEvent;
import io.getstream.models.CampaignCompletedEvent;
import io.getstream.models.CampaignStartedEvent;
import io.getstream.models.ChannelBatchCompletedEvent;
import io.getstream.models.ChannelBatchStartedEvent;
import io.getstream.models.ChannelCreatedEvent;
import io.getstream.models.ChannelDeletedEvent;
import io.getstream.models.ChannelFrozenEvent;
import io.getstream.models.ChannelHiddenEvent;
import io.getstream.models.ChannelMutedEvent;
import io.getstream.models.ChannelTruncatedEvent;
import io.getstream.models.ChannelUnFrozenEvent;
import io.getstream.models.ChannelUnmutedEvent;
import io.getstream.models.ChannelUpdatedEvent;
import io.getstream.models.ChannelVisibleEvent;
import io.getstream.models.ClosedCaptionEvent;
import io.getstream.models.CommentAddedEvent;
import io.getstream.models.CommentDeletedEvent;
import io.getstream.models.CommentReactionAddedEvent;
import io.getstream.models.CommentReactionDeletedEvent;
import io.getstream.models.CommentReactionUpdatedEvent;
import io.getstream.models.CommentRestoredEvent;
import io.getstream.models.CommentUpdatedEvent;
import io.getstream.models.CustomEvent;
import io.getstream.models.CustomVideoEvent;
import io.getstream.models.FeedCreatedEvent;
import io.getstream.models.FeedDeletedEvent;
import io.getstream.models.FeedGroupChangedEvent;
import io.getstream.models.FeedGroupDeletedEvent;
import io.getstream.models.FeedGroupRestoredEvent;
import io.getstream.models.FeedMemberAddedEvent;
import io.getstream.models.FeedMemberRemovedEvent;
import io.getstream.models.FeedMemberUpdatedEvent;
import io.getstream.models.FeedUpdatedEvent;
import io.getstream.models.FlagUpdatedEvent;
import io.getstream.models.FollowCreatedEvent;
import io.getstream.models.FollowDeletedEvent;
import io.getstream.models.FollowUpdatedEvent;
import io.getstream.models.IngressErrorEvent;
import io.getstream.models.IngressStartedEvent;
import io.getstream.models.IngressStoppedEvent;
import io.getstream.models.IntentDetectedEvent;
import io.getstream.models.KickedUserEvent;
import io.getstream.models.MaxStreakChangedEvent;
import io.getstream.models.MemberAddedEvent;
import io.getstream.models.MemberRemovedEvent;
import io.getstream.models.MemberUpdatedEvent;
import io.getstream.models.MessageDeletedEvent;
import io.getstream.models.MessageFlaggedEvent;
import io.getstream.models.MessageNewEvent;
import io.getstream.models.MessageReadEvent;
import io.getstream.models.MessageUnblockedEvent;
import io.getstream.models.MessageUndeletedEvent;
import io.getstream.models.MessageUpdatedEvent;
import io.getstream.models.ModerationAnalysisFailedEvent;
import io.getstream.models.ModerationCheckCompletedEvent;
import io.getstream.models.ModerationCustomActionEvent;
import io.getstream.models.ModerationFlaggedEvent;
import io.getstream.models.ModerationImageAnalysisCompleteEvent;
import io.getstream.models.ModerationMarkReviewedEvent;
import io.getstream.models.ModerationRulesTriggeredEvent;
import io.getstream.models.ModerationTextAnalysisCompleteEvent;
import io.getstream.models.NotificationFeedUpdatedEvent;
import io.getstream.models.NotificationMarkUnreadEvent;
import io.getstream.models.NotificationThreadMessageNewEvent;
import io.getstream.models.PendingMessageEvent;
import io.getstream.models.PermissionRequestEvent;
import io.getstream.models.ReactionDeletedEvent;
import io.getstream.models.ReactionNewEvent;
import io.getstream.models.ReactionUpdatedEvent;
import io.getstream.models.ReminderCreatedEvent;
import io.getstream.models.ReminderDeletedEvent;
import io.getstream.models.ReminderNotificationEvent;
import io.getstream.models.ReminderUpdatedEvent;
import io.getstream.models.ReviewQueueItemNewEvent;
import io.getstream.models.ReviewQueueItemUpdatedEvent;
import io.getstream.models.StoriesFeedUpdatedEvent;
import io.getstream.models.ThreadUpdatedEvent;
import io.getstream.models.UnblockedUserEvent;
import io.getstream.models.UpdatedCallPermissionsEvent;
import io.getstream.models.UserBannedEvent;
import io.getstream.models.UserDeactivatedEvent;
import io.getstream.models.UserDeletedEvent;
import io.getstream.models.UserFlaggedEvent;
import io.getstream.models.UserGroupCreatedEvent;
import io.getstream.models.UserGroupDeletedEvent;
import io.getstream.models.UserGroupMemberAddedEvent;
import io.getstream.models.UserGroupMemberRemovedEvent;
import io.getstream.models.UserGroupUpdatedEvent;
import io.getstream.models.UserMessagesDeletedEvent;
import io.getstream.models.UserMutedEvent;
import io.getstream.models.UserReactivatedEvent;
import io.getstream.models.UserUnbannedEvent;
import io.getstream.models.UserUnmutedEvent;
import io.getstream.models.UserUnreadReminderEvent;
import io.getstream.models.UserUpdatedEvent;
import java.io.ByteArrayInputStream;
import java.io.ByteArrayOutputStream;
import java.io.IOException;
import java.nio.charset.StandardCharsets;
import java.security.InvalidKeyException;
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;
import java.time.OffsetDateTime;
import java.time.format.DateTimeParseException;
import java.util.Base64;
import java.util.zip.GZIPInputStream;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;

/** Webhook utilities for Stream webhooks. */
public class Webhook {
  private static final String HMAC_SHA256 = "HmacSHA256";
  private static final ObjectMapper objectMapper =
      new ObjectMapper().configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false);

  // gzipMagic is the two-byte gzip magic prefix (RFC 1952 §2.3.1).
  // JSON cannot start with these bytes, so this gives unambiguous detection
  // for Stream's always-JSON payloads.
  private static final byte[] GZIP_MAGIC = {0x1F, (byte) 0x8B};

  /** Webhook event type constants. */
  public static class EventType {
    public static final String WILDCARD = "*";
    public static final String APPEAL_ACCEPTED = "appeal.accepted";
    public static final String APPEAL_CREATED = "appeal.created";
    public static final String APPEAL_REJECTED = "appeal.rejected";
    public static final String CALL_ACCEPTED = "call.accepted";
    public static final String CALL_BLOCKED_USER = "call.blocked_user";
    public static final String CALL_CLOSED_CAPTION = "call.closed_caption";
    public static final String CALL_CLOSED_CAPTIONS_FAILED = "call.closed_captions_failed";
    public static final String CALL_CLOSED_CAPTIONS_STARTED = "call.closed_captions_started";
    public static final String CALL_CLOSED_CAPTIONS_STOPPED = "call.closed_captions_stopped";
    public static final String CALL_CREATED = "call.created";
    public static final String CALL_DELETED = "call.deleted";
    public static final String CALL_DTMF = "call.dtmf";
    public static final String CALL_ENDED = "call.ended";
    public static final String CALL_FRAME_RECORDING_FAILED = "call.frame_recording_failed";
    public static final String CALL_FRAME_RECORDING_READY = "call.frame_recording_ready";
    public static final String CALL_FRAME_RECORDING_STARTED = "call.frame_recording_started";
    public static final String CALL_FRAME_RECORDING_STOPPED = "call.frame_recording_stopped";
    public static final String CALL_HLS_BROADCASTING_FAILED = "call.hls_broadcasting_failed";
    public static final String CALL_HLS_BROADCASTING_STARTED = "call.hls_broadcasting_started";
    public static final String CALL_HLS_BROADCASTING_STOPPED = "call.hls_broadcasting_stopped";
    public static final String CALL_KICKED_USER = "call.kicked_user";
    public static final String CALL_LIVE_STARTED = "call.live_started";
    public static final String CALL_MEMBER_ADDED = "call.member_added";
    public static final String CALL_MEMBER_REMOVED = "call.member_removed";
    public static final String CALL_MEMBER_UPDATED = "call.member_updated";
    public static final String CALL_MEMBER_UPDATED_PERMISSION = "call.member_updated_permission";
    public static final String CALL_MISSED = "call.missed";
    public static final String CALL_MODERATION_BLUR = "call.moderation_blur";
    public static final String CALL_MODERATION_WARNING = "call.moderation_warning";
    public static final String CALL_NOTIFICATION = "call.notification";
    public static final String CALL_PERMISSION_REQUEST = "call.permission_request";
    public static final String CALL_PERMISSIONS_UPDATED = "call.permissions_updated";
    public static final String CALL_REACTION_NEW = "call.reaction_new";
    public static final String CALL_RECORDING_FAILED = "call.recording_failed";
    public static final String CALL_RECORDING_READY = "call.recording_ready";
    public static final String CALL_RECORDING_STARTED = "call.recording_started";
    public static final String CALL_RECORDING_STOPPED = "call.recording_stopped";
    public static final String CALL_REJECTED = "call.rejected";
    public static final String CALL_RING = "call.ring";
    public static final String CALL_RTMP_BROADCAST_FAILED = "call.rtmp_broadcast_failed";
    public static final String CALL_RTMP_BROADCAST_STARTED = "call.rtmp_broadcast_started";
    public static final String CALL_RTMP_BROADCAST_STOPPED = "call.rtmp_broadcast_stopped";
    public static final String CALL_SESSION_ENDED = "call.session_ended";
    public static final String CALL_SESSION_PARTICIPANT_COUNT_UPDATED =
        "call.session_participant_count_updated";
    public static final String CALL_SESSION_PARTICIPANT_JOINED = "call.session_participant_joined";
    public static final String CALL_SESSION_PARTICIPANT_LEFT = "call.session_participant_left";
    public static final String CALL_SESSION_STARTED = "call.session_started";
    public static final String CALL_STATS_REPORT_READY = "call.stats_report_ready";
    public static final String CALL_TRANSCRIPTION_FAILED = "call.transcription_failed";
    public static final String CALL_TRANSCRIPTION_READY = "call.transcription_ready";
    public static final String CALL_TRANSCRIPTION_STARTED = "call.transcription_started";
    public static final String CALL_TRANSCRIPTION_STOPPED = "call.transcription_stopped";
    public static final String CALL_UNBLOCKED_USER = "call.unblocked_user";
    public static final String CALL_UPDATED = "call.updated";
    public static final String CALL_USER_FEEDBACK_SUBMITTED = "call.user_feedback_submitted";
    public static final String CALL_USER_MUTED = "call.user_muted";
    public static final String CAMPAIGN_COMPLETED = "campaign.completed";
    public static final String CAMPAIGN_STARTED = "campaign.started";
    public static final String CHANNEL_CREATED = "channel.created";
    public static final String CHANNEL_DELETED = "channel.deleted";
    public static final String CHANNEL_FROZEN = "channel.frozen";
    public static final String CHANNEL_HIDDEN = "channel.hidden";
    public static final String CHANNEL_MAX_STREAK_CHANGED = "channel.max_streak_changed";
    public static final String CHANNEL_MUTED = "channel.muted";
    public static final String CHANNEL_TRUNCATED = "channel.truncated";
    public static final String CHANNEL_UNFROZEN = "channel.unfrozen";
    public static final String CHANNEL_UNMUTED = "channel.unmuted";
    public static final String CHANNEL_UPDATED = "channel.updated";
    public static final String CHANNEL_VISIBLE = "channel.visible";
    public static final String CHANNEL_BATCH_UPDATE_COMPLETED = "channel_batch_update.completed";
    public static final String CHANNEL_BATCH_UPDATE_STARTED = "channel_batch_update.started";
    public static final String CUSTOM = "custom";
    public static final String EXPORT_BULK_IMAGE_MODERATION_ERROR =
        "export.bulk_image_moderation.error";
    public static final String EXPORT_BULK_IMAGE_MODERATION_SUCCESS =
        "export.bulk_image_moderation.success";
    public static final String EXPORT_CHANNELS_ERROR = "export.channels.error";
    public static final String EXPORT_CHANNELS_SUCCESS = "export.channels.success";
    public static final String EXPORT_MODERATION_LOGS_ERROR = "export.moderation_logs.error";
    public static final String EXPORT_MODERATION_LOGS_SUCCESS = "export.moderation_logs.success";
    public static final String EXPORT_REVIEW_QUEUE_ERROR = "export.review_queue.error";
    public static final String EXPORT_REVIEW_QUEUE_SUCCESS = "export.review_queue.success";
    public static final String EXPORT_USERS_ERROR = "export.users.error";
    public static final String EXPORT_USERS_SUCCESS = "export.users.success";
    public static final String FEEDS_ACTIVITY_ADDED = "feeds.activity.added";
    public static final String FEEDS_ACTIVITY_DELETED = "feeds.activity.deleted";
    public static final String FEEDS_ACTIVITY_FEEDBACK = "feeds.activity.feedback";
    public static final String FEEDS_ACTIVITY_MARKED = "feeds.activity.marked";
    public static final String FEEDS_ACTIVITY_PINNED = "feeds.activity.pinned";
    public static final String FEEDS_ACTIVITY_REACTION_ADDED = "feeds.activity.reaction.added";
    public static final String FEEDS_ACTIVITY_REACTION_DELETED = "feeds.activity.reaction.deleted";
    public static final String FEEDS_ACTIVITY_REACTION_UPDATED = "feeds.activity.reaction.updated";
    public static final String FEEDS_ACTIVITY_REMOVED_FROM_FEED =
        "feeds.activity.removed_from_feed";
    public static final String FEEDS_ACTIVITY_RESTORED = "feeds.activity.restored";
    public static final String FEEDS_ACTIVITY_UNPINNED = "feeds.activity.unpinned";
    public static final String FEEDS_ACTIVITY_UPDATED = "feeds.activity.updated";
    public static final String FEEDS_BOOKMARK_ADDED = "feeds.bookmark.added";
    public static final String FEEDS_BOOKMARK_DELETED = "feeds.bookmark.deleted";
    public static final String FEEDS_BOOKMARK_UPDATED = "feeds.bookmark.updated";
    public static final String FEEDS_BOOKMARK_FOLDER_DELETED = "feeds.bookmark_folder.deleted";
    public static final String FEEDS_BOOKMARK_FOLDER_UPDATED = "feeds.bookmark_folder.updated";
    public static final String FEEDS_COMMENT_ADDED = "feeds.comment.added";
    public static final String FEEDS_COMMENT_DELETED = "feeds.comment.deleted";
    public static final String FEEDS_COMMENT_REACTION_ADDED = "feeds.comment.reaction.added";
    public static final String FEEDS_COMMENT_REACTION_DELETED = "feeds.comment.reaction.deleted";
    public static final String FEEDS_COMMENT_REACTION_UPDATED = "feeds.comment.reaction.updated";
    public static final String FEEDS_COMMENT_RESTORED = "feeds.comment.restored";
    public static final String FEEDS_COMMENT_UPDATED = "feeds.comment.updated";
    public static final String FEEDS_FEED_CREATED = "feeds.feed.created";
    public static final String FEEDS_FEED_DELETED = "feeds.feed.deleted";
    public static final String FEEDS_FEED_UPDATED = "feeds.feed.updated";
    public static final String FEEDS_FEED_GROUP_CHANGED = "feeds.feed_group.changed";
    public static final String FEEDS_FEED_GROUP_DELETED = "feeds.feed_group.deleted";
    public static final String FEEDS_FEED_GROUP_RESTORED = "feeds.feed_group.restored";
    public static final String FEEDS_FEED_MEMBER_ADDED = "feeds.feed_member.added";
    public static final String FEEDS_FEED_MEMBER_REMOVED = "feeds.feed_member.removed";
    public static final String FEEDS_FEED_MEMBER_UPDATED = "feeds.feed_member.updated";
    public static final String FEEDS_FOLLOW_CREATED = "feeds.follow.created";
    public static final String FEEDS_FOLLOW_DELETED = "feeds.follow.deleted";
    public static final String FEEDS_FOLLOW_UPDATED = "feeds.follow.updated";
    public static final String FEEDS_NOTIFICATION_FEED_UPDATED = "feeds.notification_feed.updated";
    public static final String FEEDS_STORIES_FEED_UPDATED = "feeds.stories_feed.updated";
    public static final String FLAG_UPDATED = "flag.updated";
    public static final String IMPORT_ERROR = "import.error";
    public static final String IMPORT_SUCCESS = "import.success";
    public static final String INGRESS_ERROR = "ingress.error";
    public static final String INGRESS_STARTED = "ingress.started";
    public static final String INGRESS_STOPPED = "ingress.stopped";
    public static final String MEMBER_ADDED = "member.added";
    public static final String MEMBER_REMOVED = "member.removed";
    public static final String MEMBER_UPDATED = "member.updated";
    public static final String MESSAGE_DELETED = "message.deleted";
    public static final String MESSAGE_FLAGGED = "message.flagged";
    public static final String MESSAGE_NEW = "message.new";
    public static final String MESSAGE_PENDING = "message.pending";
    public static final String MESSAGE_READ = "message.read";
    public static final String MESSAGE_UNBLOCKED = "message.unblocked";
    public static final String MESSAGE_UNDELETED = "message.undeleted";
    public static final String MESSAGE_UPDATED = "message.updated";
    public static final String MODERATION_ANALYSIS_FAILED = "moderation.analysis.failed";
    public static final String MODERATION_CUSTOM_ACTION = "moderation.custom_action";
    public static final String MODERATION_FLAGGED = "moderation.flagged";
    public static final String MODERATION_IMAGE_ANALYSIS_COMPLETE =
        "moderation.image_analysis.complete";
    public static final String MODERATION_INTENT_DETECTED = "moderation.intent_detected";
    public static final String MODERATION_MARK_REVIEWED = "moderation.mark_reviewed";
    public static final String MODERATION_TEXT_ANALYSIS_COMPLETE =
        "moderation.text_analysis.complete";
    public static final String MODERATION_CHECK_COMPLETED = "moderation_check.completed";
    public static final String MODERATION_RULE_TRIGGERED = "moderation_rule.triggered";
    public static final String NOTIFICATION_MARK_UNREAD = "notification.mark_unread";
    public static final String NOTIFICATION_REMINDER_DUE = "notification.reminder_due";
    public static final String NOTIFICATION_THREAD_MESSAGE_NEW = "notification.thread_message_new";
    public static final String REACTION_DELETED = "reaction.deleted";
    public static final String REACTION_NEW = "reaction.new";
    public static final String REACTION_UPDATED = "reaction.updated";
    public static final String REMINDER_CREATED = "reminder.created";
    public static final String REMINDER_DELETED = "reminder.deleted";
    public static final String REMINDER_UPDATED = "reminder.updated";
    public static final String REVIEW_QUEUE_ITEM_NEW = "review_queue_item.new";
    public static final String REVIEW_QUEUE_ITEM_UPDATED = "review_queue_item.updated";
    public static final String THREAD_UPDATED = "thread.updated";
    public static final String USER_BANNED = "user.banned";
    public static final String USER_DEACTIVATED = "user.deactivated";
    public static final String USER_DELETED = "user.deleted";
    public static final String USER_FLAGGED = "user.flagged";
    public static final String USER_MESSAGES_DELETED = "user.messages.deleted";
    public static final String USER_MUTED = "user.muted";
    public static final String USER_REACTIVATED = "user.reactivated";
    public static final String USER_UNBANNED = "user.unbanned";
    public static final String USER_UNMUTED = "user.unmuted";
    public static final String USER_UNREAD_MESSAGE_REMINDER = "user.unread_message_reminder";
    public static final String USER_UPDATED = "user.updated";
    public static final String USER_GROUP_CREATED = "user_group.created";
    public static final String USER_GROUP_DELETED = "user_group.deleted";
    public static final String USER_GROUP_MEMBER_ADDED = "user_group.member_added";
    public static final String USER_GROUP_MEMBER_REMOVED = "user_group.member_removed";
    public static final String USER_GROUP_UPDATED = "user_group.updated";
  }

  /**
   * Extract the event type from a raw webhook payload.
   *
   * @param rawEvent The raw webhook payload as a byte array
   * @return The event type string (e.g., "message.new"), or null if not found
   */
  public static String getEventType(byte[] rawEvent) {
    try {
      JsonNode node = objectMapper.readTree(rawEvent);
      JsonNode typeNode = node.get("type");
      return typeNode != null ? typeNode.asText() : null;
    } catch (IOException e) {
      return null;
    }
  }

  /**
   * Extract the event type from a raw webhook payload.
   *
   * @param rawEvent The raw webhook payload as a string
   * @return The event type string (e.g., "message.new"), or null if not found
   */
  public static String getEventType(String rawEvent) {
    return getEventType(rawEvent.getBytes(StandardCharsets.UTF_8));
  }

  /**
   * Deserialize a raw webhook payload into a typed event object.
   *
   * @param rawEvent The raw webhook payload as a byte array
   * @return A typed event object corresponding to the event type
   * @throws InvalidWebhookError if the event type is unknown or deserialization fails
   */
  public static Object parseWebhookEvent(byte[] rawEvent) throws InvalidWebhookError {
    String eventType = extractEventType(rawEvent);
    Class<?> eventClass = getEventClass(eventType);
    if (eventClass == null) {
      throw new InvalidWebhookError(
          InvalidWebhookError.INVALID_JSON + ": Unknown webhook event type: " + eventType);
    }
    try {
      return objectMapper.readValue(rawEvent, eventClass);
    } catch (IOException e) {
      throw new InvalidWebhookError(
          InvalidWebhookError.INVALID_JSON
              + ": Failed to deserialize webhook event: "
              + e.getMessage(),
          e);
    }
  }

  private static String extractEventType(byte[] rawEvent) throws InvalidWebhookError {
    JsonNode node;
    try {
      node = objectMapper.readTree(rawEvent);
    } catch (IOException e) {
      throw new InvalidWebhookError(
          InvalidWebhookError.INVALID_JSON
              + ": Webhook payload is not valid JSON: "
              + e.getMessage(),
          e);
    }
    JsonNode typeNode = node.get("type");
    if (typeNode == null || typeNode.asText().isEmpty()) {
      throw new InvalidWebhookError(
          InvalidWebhookError.INVALID_JSON + ": Webhook payload missing 'type' field");
    }
    return typeNode.asText();
  }

  /**
   * Deserialize a raw webhook payload into a typed event object.
   *
   * @param rawEvent The raw webhook payload as a string
   * @return A typed event object corresponding to the event type
   * @throws InvalidWebhookError if the event type is unknown or deserialization fails
   */
  public static Object parseWebhookEvent(String rawEvent) throws InvalidWebhookError {
    return parseWebhookEvent(rawEvent.getBytes(StandardCharsets.UTF_8));
  }

  /**
   * Map an event type discriminator to its generated event class. Returns null when the
   * discriminator is not recognized; callers decide whether to throw (parseWebhookEvent) or fall
   * back to UnknownEvent (parseEvent).
   */
  private static Class<?> getEventClass(String eventType) {
    switch (eventType) {
      case "*":
        return CustomEvent.class;
      case "appeal.accepted":
        return AppealAcceptedEvent.class;
      case "appeal.created":
        return AppealCreatedEvent.class;
      case "appeal.rejected":
        return AppealRejectedEvent.class;
      case "call.accepted":
        return CallAcceptedEvent.class;
      case "call.blocked_user":
        return BlockedUserEvent.class;
      case "call.closed_caption":
        return ClosedCaptionEvent.class;
      case "call.closed_captions_failed":
        return CallClosedCaptionsFailedEvent.class;
      case "call.closed_captions_started":
        return CallClosedCaptionsStartedEvent.class;
      case "call.closed_captions_stopped":
        return CallClosedCaptionsStoppedEvent.class;
      case "call.created":
        return CallCreatedEvent.class;
      case "call.deleted":
        return CallDeletedEvent.class;
      case "call.dtmf":
        return CallDTMFEvent.class;
      case "call.ended":
        return CallEndedEvent.class;
      case "call.frame_recording_failed":
        return CallFrameRecordingFailedEvent.class;
      case "call.frame_recording_ready":
        return CallFrameRecordingFrameReadyEvent.class;
      case "call.frame_recording_started":
        return CallFrameRecordingStartedEvent.class;
      case "call.frame_recording_stopped":
        return CallFrameRecordingStoppedEvent.class;
      case "call.hls_broadcasting_failed":
        return CallHLSBroadcastingFailedEvent.class;
      case "call.hls_broadcasting_started":
        return CallHLSBroadcastingStartedEvent.class;
      case "call.hls_broadcasting_stopped":
        return CallHLSBroadcastingStoppedEvent.class;
      case "call.kicked_user":
        return KickedUserEvent.class;
      case "call.live_started":
        return CallLiveStartedEvent.class;
      case "call.member_added":
        return CallMemberAddedEvent.class;
      case "call.member_removed":
        return CallMemberRemovedEvent.class;
      case "call.member_updated":
        return CallMemberUpdatedEvent.class;
      case "call.member_updated_permission":
        return CallMemberUpdatedPermissionEvent.class;
      case "call.missed":
        return CallMissedEvent.class;
      case "call.moderation_blur":
        return CallModerationBlurEvent.class;
      case "call.moderation_warning":
        return CallModerationWarningEvent.class;
      case "call.notification":
        return CallNotificationEvent.class;
      case "call.permission_request":
        return PermissionRequestEvent.class;
      case "call.permissions_updated":
        return UpdatedCallPermissionsEvent.class;
      case "call.reaction_new":
        return CallReactionEvent.class;
      case "call.recording_failed":
        return CallRecordingFailedEvent.class;
      case "call.recording_ready":
        return CallRecordingReadyEvent.class;
      case "call.recording_started":
        return CallRecordingStartedEvent.class;
      case "call.recording_stopped":
        return CallRecordingStoppedEvent.class;
      case "call.rejected":
        return CallRejectedEvent.class;
      case "call.ring":
        return CallRingEvent.class;
      case "call.rtmp_broadcast_failed":
        return CallRtmpBroadcastFailedEvent.class;
      case "call.rtmp_broadcast_started":
        return CallRtmpBroadcastStartedEvent.class;
      case "call.rtmp_broadcast_stopped":
        return CallRtmpBroadcastStoppedEvent.class;
      case "call.session_ended":
        return CallSessionEndedEvent.class;
      case "call.session_participant_count_updated":
        return CallSessionParticipantCountsUpdatedEvent.class;
      case "call.session_participant_joined":
        return CallSessionParticipantJoinedEvent.class;
      case "call.session_participant_left":
        return CallSessionParticipantLeftEvent.class;
      case "call.session_started":
        return CallSessionStartedEvent.class;
      case "call.stats_report_ready":
        return CallStatsReportReadyEvent.class;
      case "call.transcription_failed":
        return CallTranscriptionFailedEvent.class;
      case "call.transcription_ready":
        return CallTranscriptionReadyEvent.class;
      case "call.transcription_started":
        return CallTranscriptionStartedEvent.class;
      case "call.transcription_stopped":
        return CallTranscriptionStoppedEvent.class;
      case "call.unblocked_user":
        return UnblockedUserEvent.class;
      case "call.updated":
        return CallUpdatedEvent.class;
      case "call.user_feedback_submitted":
        return CallUserFeedbackSubmittedEvent.class;
      case "call.user_muted":
        return CallUserMutedEvent.class;
      case "campaign.completed":
        return CampaignCompletedEvent.class;
      case "campaign.started":
        return CampaignStartedEvent.class;
      case "channel.created":
        return ChannelCreatedEvent.class;
      case "channel.deleted":
        return ChannelDeletedEvent.class;
      case "channel.frozen":
        return ChannelFrozenEvent.class;
      case "channel.hidden":
        return ChannelHiddenEvent.class;
      case "channel.max_streak_changed":
        return MaxStreakChangedEvent.class;
      case "channel.muted":
        return ChannelMutedEvent.class;
      case "channel.truncated":
        return ChannelTruncatedEvent.class;
      case "channel.unfrozen":
        return ChannelUnFrozenEvent.class;
      case "channel.unmuted":
        return ChannelUnmutedEvent.class;
      case "channel.updated":
        return ChannelUpdatedEvent.class;
      case "channel.visible":
        return ChannelVisibleEvent.class;
      case "channel_batch_update.completed":
        return ChannelBatchCompletedEvent.class;
      case "channel_batch_update.started":
        return ChannelBatchStartedEvent.class;
      case "custom":
        return CustomVideoEvent.class;
      case "export.bulk_image_moderation.error":
        return AsyncExportErrorEvent.class;
      case "export.bulk_image_moderation.success":
        return AsyncBulkImageModerationEvent.class;
      case "export.channels.error":
        return AsyncExportErrorEvent.class;
      case "export.channels.success":
        return AsyncExportChannelsEvent.class;
      case "export.moderation_logs.error":
        return AsyncExportErrorEvent.class;
      case "export.moderation_logs.success":
        return AsyncExportModerationLogsEvent.class;
      case "export.review_queue.error":
        return AsyncExportErrorEvent.class;
      case "export.review_queue.success":
        return AsyncExportReviewQueueEvent.class;
      case "export.users.error":
        return AsyncExportErrorEvent.class;
      case "export.users.success":
        return AsyncExportUsersEvent.class;
      case "feeds.activity.added":
        return ActivityAddedEvent.class;
      case "feeds.activity.deleted":
        return ActivityDeletedEvent.class;
      case "feeds.activity.feedback":
        return ActivityFeedbackEvent.class;
      case "feeds.activity.marked":
        return ActivityMarkEvent.class;
      case "feeds.activity.pinned":
        return ActivityPinnedEvent.class;
      case "feeds.activity.reaction.added":
        return ActivityReactionAddedEvent.class;
      case "feeds.activity.reaction.deleted":
        return ActivityReactionDeletedEvent.class;
      case "feeds.activity.reaction.updated":
        return ActivityReactionUpdatedEvent.class;
      case "feeds.activity.removed_from_feed":
        return ActivityRemovedFromFeedEvent.class;
      case "feeds.activity.restored":
        return ActivityRestoredEvent.class;
      case "feeds.activity.unpinned":
        return ActivityUnpinnedEvent.class;
      case "feeds.activity.updated":
        return ActivityUpdatedEvent.class;
      case "feeds.bookmark.added":
        return BookmarkAddedEvent.class;
      case "feeds.bookmark.deleted":
        return BookmarkDeletedEvent.class;
      case "feeds.bookmark.updated":
        return BookmarkUpdatedEvent.class;
      case "feeds.bookmark_folder.deleted":
        return BookmarkFolderDeletedEvent.class;
      case "feeds.bookmark_folder.updated":
        return BookmarkFolderUpdatedEvent.class;
      case "feeds.comment.added":
        return CommentAddedEvent.class;
      case "feeds.comment.deleted":
        return CommentDeletedEvent.class;
      case "feeds.comment.reaction.added":
        return CommentReactionAddedEvent.class;
      case "feeds.comment.reaction.deleted":
        return CommentReactionDeletedEvent.class;
      case "feeds.comment.reaction.updated":
        return CommentReactionUpdatedEvent.class;
      case "feeds.comment.restored":
        return CommentRestoredEvent.class;
      case "feeds.comment.updated":
        return CommentUpdatedEvent.class;
      case "feeds.feed.created":
        return FeedCreatedEvent.class;
      case "feeds.feed.deleted":
        return FeedDeletedEvent.class;
      case "feeds.feed.updated":
        return FeedUpdatedEvent.class;
      case "feeds.feed_group.changed":
        return FeedGroupChangedEvent.class;
      case "feeds.feed_group.deleted":
        return FeedGroupDeletedEvent.class;
      case "feeds.feed_group.restored":
        return FeedGroupRestoredEvent.class;
      case "feeds.feed_member.added":
        return FeedMemberAddedEvent.class;
      case "feeds.feed_member.removed":
        return FeedMemberRemovedEvent.class;
      case "feeds.feed_member.updated":
        return FeedMemberUpdatedEvent.class;
      case "feeds.follow.created":
        return FollowCreatedEvent.class;
      case "feeds.follow.deleted":
        return FollowDeletedEvent.class;
      case "feeds.follow.updated":
        return FollowUpdatedEvent.class;
      case "feeds.notification_feed.updated":
        return NotificationFeedUpdatedEvent.class;
      case "feeds.stories_feed.updated":
        return StoriesFeedUpdatedEvent.class;
      case "flag.updated":
        return FlagUpdatedEvent.class;
      case "import.error":
        return AsyncImportErrorEvent.class;
      case "import.success":
        return AsyncImportSuccessEvent.class;
      case "ingress.error":
        return IngressErrorEvent.class;
      case "ingress.started":
        return IngressStartedEvent.class;
      case "ingress.stopped":
        return IngressStoppedEvent.class;
      case "member.added":
        return MemberAddedEvent.class;
      case "member.removed":
        return MemberRemovedEvent.class;
      case "member.updated":
        return MemberUpdatedEvent.class;
      case "message.deleted":
        return MessageDeletedEvent.class;
      case "message.flagged":
        return MessageFlaggedEvent.class;
      case "message.new":
        return MessageNewEvent.class;
      case "message.pending":
        return PendingMessageEvent.class;
      case "message.read":
        return MessageReadEvent.class;
      case "message.unblocked":
        return MessageUnblockedEvent.class;
      case "message.undeleted":
        return MessageUndeletedEvent.class;
      case "message.updated":
        return MessageUpdatedEvent.class;
      case "moderation.analysis.failed":
        return ModerationAnalysisFailedEvent.class;
      case "moderation.custom_action":
        return ModerationCustomActionEvent.class;
      case "moderation.flagged":
        return ModerationFlaggedEvent.class;
      case "moderation.image_analysis.complete":
        return ModerationImageAnalysisCompleteEvent.class;
      case "moderation.intent_detected":
        return IntentDetectedEvent.class;
      case "moderation.mark_reviewed":
        return ModerationMarkReviewedEvent.class;
      case "moderation.text_analysis.complete":
        return ModerationTextAnalysisCompleteEvent.class;
      case "moderation_check.completed":
        return ModerationCheckCompletedEvent.class;
      case "moderation_rule.triggered":
        return ModerationRulesTriggeredEvent.class;
      case "notification.mark_unread":
        return NotificationMarkUnreadEvent.class;
      case "notification.reminder_due":
        return ReminderNotificationEvent.class;
      case "notification.thread_message_new":
        return NotificationThreadMessageNewEvent.class;
      case "reaction.deleted":
        return ReactionDeletedEvent.class;
      case "reaction.new":
        return ReactionNewEvent.class;
      case "reaction.updated":
        return ReactionUpdatedEvent.class;
      case "reminder.created":
        return ReminderCreatedEvent.class;
      case "reminder.deleted":
        return ReminderDeletedEvent.class;
      case "reminder.updated":
        return ReminderUpdatedEvent.class;
      case "review_queue_item.new":
        return ReviewQueueItemNewEvent.class;
      case "review_queue_item.updated":
        return ReviewQueueItemUpdatedEvent.class;
      case "thread.updated":
        return ThreadUpdatedEvent.class;
      case "user.banned":
        return UserBannedEvent.class;
      case "user.deactivated":
        return UserDeactivatedEvent.class;
      case "user.deleted":
        return UserDeletedEvent.class;
      case "user.flagged":
        return UserFlaggedEvent.class;
      case "user.messages.deleted":
        return UserMessagesDeletedEvent.class;
      case "user.muted":
        return UserMutedEvent.class;
      case "user.reactivated":
        return UserReactivatedEvent.class;
      case "user.unbanned":
        return UserUnbannedEvent.class;
      case "user.unmuted":
        return UserUnmutedEvent.class;
      case "user.unread_message_reminder":
        return UserUnreadReminderEvent.class;
      case "user.updated":
        return UserUpdatedEvent.class;
      case "user_group.created":
        return UserGroupCreatedEvent.class;
      case "user_group.deleted":
        return UserGroupDeletedEvent.class;
      case "user_group.member_added":
        return UserGroupMemberAddedEvent.class;
      case "user_group.member_removed":
        return UserGroupMemberRemovedEvent.class;
      case "user_group.updated":
        return UserGroupUpdatedEvent.class;
      default:
        return null;
    }
  }

  /**
   * Thrown for every webhook handling failure: signature mismatch, invalid JSON, missing/non-string
   * {@code type} field, gzip-prefixed body that fails to decompress, invalid base64 in a queue
   * body, or a malformed SNS envelope.
   *
   * <p>Catch this single class for any webhook problem; filter on the message text or against the
   * failure-mode constants below to differentiate.
   */
  public static class InvalidWebhookError extends StreamException {
    public static final String SIGNATURE_MISMATCH = "signature mismatch";
    public static final String INVALID_BASE64 = "invalid base64 encoding";
    public static final String GZIP_FAILED = "gzip decompression failed";
    public static final String INVALID_JSON = "invalid JSON payload";

    public InvalidWebhookError(String message) {
      super(message, (Throwable) null);
    }

    public InvalidWebhookError(String message, Throwable cause) {
      super(message, cause);
    }
  }

  /**
   * @deprecated Renamed to {@link InvalidWebhookError}. Will be removed in the next minor release.
   *     Kept as a subclass so existing {@code catch (WebhookException e)} clauses continue to
   *     compile and catch the new class.
   */
  @Deprecated
  public static class WebhookException extends InvalidWebhookError {
    public WebhookException(String message) {
      super(message);
    }

    public WebhookException(String message, Throwable cause) {
      super(message, cause);
    }
  }

  /**
   * Returned by {@link #parseEvent(byte[])} when the type discriminator is well-formed but unknown
   * to this SDK version. Forward-compat surface for new event types.
   *
   * <p>To handle unknown events, check the result type with {@code instanceof UnknownEvent} after
   * calling {@code parseEvent}.
   */
  public static class UnknownEvent {
    private final String type;
    private final OffsetDateTime createdAt;
    private final JsonNode raw;

    public UnknownEvent(String type, OffsetDateTime createdAt, JsonNode raw) {
      this.type = type;
      this.createdAt = createdAt;
      this.raw = raw;
    }

    /** The unrecognized discriminator value. */
    public String getType() {
      return type;
    }

    /** Parsed timestamp from the envelope, or null if the field was missing or unparseable. */
    public OffsetDateTime getCreatedAt() {
      return createdAt;
    }

    /** The full parsed JSON payload, for inspection. */
    public JsonNode getRaw() {
      return raw;
    }
  }

  /**
   * Verify the HMAC-SHA256 signature of a webhook payload.
   *
   * @param body The raw request body as a byte array
   * @param signature The signature from the X-Signature header
   * @param secret Your webhook secret (found in the Stream Dashboard)
   * @return true if the signature is valid, false otherwise
   */
  public static boolean verifySignature(byte[] body, String signature, String secret) {
    try {
      Mac mac = Mac.getInstance(HMAC_SHA256);
      SecretKeySpec secretKey =
          new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), HMAC_SHA256);
      mac.init(secretKey);
      byte[] hash = mac.doFinal(body);
      String expected = bytesToHex(hash);
      return MessageDigest.isEqual(
          signature.getBytes(StandardCharsets.UTF_8), expected.getBytes(StandardCharsets.UTF_8));
    } catch (NoSuchAlgorithmException | InvalidKeyException e) {
      return false;
    }
  }

  /**
   * Verify the HMAC-SHA256 signature of a webhook payload.
   *
   * @param body The raw request body as a string
   * @param signature The signature from the X-Signature header
   * @param secret Your webhook secret (found in the Stream Dashboard)
   * @return true if the signature is valid, false otherwise
   */
  public static boolean verifySignature(String body, String signature, String secret) {
    return verifySignature(body.getBytes(StandardCharsets.UTF_8), signature, secret);
  }

  /**
   * Decompress the body if it is gzip-prefixed, otherwise return it as-is.
   *
   * <p>Detection uses the first two bytes (0x1F 0x8B). This is reliable because Stream webhook
   * bodies are always JSON, and JSON cannot start with 0x1F.
   *
   * @param body the raw request body, possibly gzip-compressed
   * @return the uncompressed bytes (or {@code body} unchanged if no gzip prefix)
   * @throws InvalidWebhookError if the body has the gzip magic prefix but isn't a valid gzip stream
   */
  public static byte[] gunzipPayload(byte[] body) throws InvalidWebhookError {
    if (body == null || body.length < 2 || body[0] != GZIP_MAGIC[0] || body[1] != GZIP_MAGIC[1]) {
      return body == null ? new byte[0] : body;
    }
    try (ByteArrayInputStream bin = new ByteArrayInputStream(body);
        GZIPInputStream gz = new GZIPInputStream(bin);
        ByteArrayOutputStream out = new ByteArrayOutputStream()) {
      byte[] buf = new byte[4096];
      int n;
      while ((n = gz.read(buf)) != -1) {
        out.write(buf, 0, n);
      }
      return out.toByteArray();
    } catch (IOException e) {
      throw new InvalidWebhookError(InvalidWebhookError.GZIP_FAILED + ": " + e.getMessage(), e);
    }
  }

  /**
   * Decode an SQS Message Body: try base64 first, fall back to raw bytes if base64 fails, then
   * gunzip if gzip-prefixed.
   *
   * <p>Wire format (per CHA-3071): SQS bodies are raw JSON when {@code
   * enable_hook_payload_compression} is off (today's default for all existing apps), and
   * base64(gzip(json)) when it's on. This helper handles both: raw JSON starts with '{' which is
   * not valid base64, so the base64 decode fails and we fall through to raw bytes, then {@link
   * #gunzipPayload(byte[])}'s magic-byte detection decides whether to decompress.
   *
   * <p>{@link #parseSqs(String)} sits on top of this and works transparently for both wire formats:
   * no caller code change, no flag, no header.
   *
   * @throws InvalidWebhookError if gzip decompression fails (only when input has gzip magic prefix)
   */
  public static byte[] decodeSqsPayload(String messageBody) throws InvalidWebhookError {
    if (messageBody == null) {
      throw new InvalidWebhookError(
          InvalidWebhookError.INVALID_JSON + ": messageBody must not be null");
    }
    byte[] decoded;
    try {
      decoded = Base64.getDecoder().decode(messageBody);
    } catch (IllegalArgumentException e) {
      // Not base64, so treat input as raw bytes (uncompressed wire format).
      decoded = messageBody.getBytes(StandardCharsets.UTF_8);
    }
    return gunzipPayload(decoded);
  }

  /**
   * Return the inner {@code Message} field when {@code body} is a standard SNS notification
   * envelope JSON; otherwise return {@code body} unchanged so a pre-extracted Message string flows
   * through.
   *
   * <p>Heuristic: try to JSON-parse the input. If it yields an object with a string {@code Message}
   * field, that's the envelope shape; return the Message. Otherwise the input is presumed to BE the
   * pre-extracted Message (base64-encoded bytes are not valid JSON, so this falls through cleanly).
   */
  private static String unwrapSnsNotificationBody(String body) {
    try {
      JsonNode env = objectMapper.readTree(body);
      JsonNode msg = env != null ? env.get("Message") : null;
      if (msg != null && msg.isTextual()) {
        return msg.asText();
      }
    } catch (IOException e) {
      // not JSON, so fall through to treating body as a bare Message string
    }
    return body;
  }

  /**
   * Decode an SNS notification body. Accepts either:
   *
   * <ul>
   *   <li>a full SNS HTTP notification envelope JSON ({@code
   *       {"Type":"Notification","Message":"<base64>",...}}), or
   *   <li>a pre-extracted Message string (forwarded-through-SQS path).
   * </ul>
   *
   * The inner payload is then base64-decoded and gunzipped via {@link #decodeSqsPayload(String)}.
   */
  public static byte[] decodeSnsPayload(String notificationBody) throws InvalidWebhookError {
    if (notificationBody == null) {
      throw new InvalidWebhookError(
          InvalidWebhookError.INVALID_JSON + ": notificationBody must not be null");
    }
    return decodeSqsPayload(unwrapSnsNotificationBody(notificationBody));
  }

  /**
   * Parse a webhook payload and return the typed event for known discriminators or {@link
   * UnknownEvent} for well-formed-but-unknown ones.
   *
   * <p>Distinct from {@link #parseWebhookEvent(byte[])}: {@code parseEvent} returns an {@code
   * UnknownEvent} on unrecognized discriminators (forward-compat); {@code parseWebhookEvent}
   * throws.
   *
   * @return the typed event (a generated event class) or an {@link UnknownEvent} instance
   * @throws InvalidWebhookError for invalid JSON, missing/non-string type field, or any
   *     deserialization failure on a known type
   */
  public static Object parseEvent(byte[] payload) throws InvalidWebhookError {
    if (payload == null || payload.length == 0) {
      throw new InvalidWebhookError(
          InvalidWebhookError.INVALID_JSON + ": payload must not be empty");
    }
    JsonNode root;
    try {
      root = objectMapper.readTree(payload);
    } catch (IOException e) {
      throw new InvalidWebhookError(
          InvalidWebhookError.INVALID_JSON + ": failed to parse webhook payload: " + e.getMessage(),
          e);
    }
    if (root == null || !root.isObject()) {
      throw new InvalidWebhookError(
          InvalidWebhookError.INVALID_JSON + ": webhook payload must be a JSON object");
    }
    JsonNode typeNode = root.get("type");
    if (typeNode == null || !typeNode.isTextual() || typeNode.asText().isEmpty()) {
      throw new InvalidWebhookError(
          InvalidWebhookError.INVALID_JSON + ": webhook payload missing 'type' string field");
    }
    String eventType = typeNode.asText();

    Class<?> klass = getEventClass(eventType);
    if (klass == null) {
      OffsetDateTime createdAt = null;
      JsonNode createdNode = root.get("created_at");
      if (createdNode != null && createdNode.isTextual()) {
        try {
          createdAt = OffsetDateTime.parse(createdNode.asText());
        } catch (DateTimeParseException ignored) {
          // leave null
        }
      }
      return new UnknownEvent(eventType, createdAt, root);
    }

    try {
      return objectMapper.treeToValue(root, klass);
    } catch (JsonProcessingException e) {
      throw new InvalidWebhookError(
          InvalidWebhookError.INVALID_JSON + ": failed to deserialize event: " + e.getMessage(), e);
    }
  }

  /**
   * HTTP composite: gunzip (if gzip-prefixed) then verify HMAC-SHA256 then parse.
   *
   * <p>The signature header is X-Signature. The signature is HMAC-SHA256 of the
   * <em>uncompressed</em> JSON body, hex-encoded. Magic-byte detection means callers can pass
   * either the raw HTTP body or already-decompressed bytes; both work.
   *
   * @throws InvalidWebhookError for every failure mode: signature mismatch, gunzip failure, JSON
   *     parse, type dispatch, or event deserialization failure. Filter on the message text (or the
   *     failure-mode constants on {@link InvalidWebhookError}) to differentiate modes.
   */
  public static Object verifyAndParseWebhook(byte[] body, String signature, String secret)
      throws InvalidWebhookError {
    byte[] payload = gunzipPayload(body);
    if (!verifySignature(payload, signature, secret)) {
      throw new InvalidWebhookError(InvalidWebhookError.SIGNATURE_MISMATCH);
    }
    return parseEvent(payload);
  }

  /**
   * SQS composite: base64-decode then gunzip (if gzip-prefixed) then parse.
   *
   * <p>The backend emits no signature attribute on SQS messages today; this helper therefore
   * performs no signature verification. If a signed variant is added later, it'll be a separate
   * function rather than retrofitting this signature.
   */
  public static Object parseSqs(String messageBody) throws InvalidWebhookError {
    return parseEvent(decodeSqsPayload(messageBody));
  }

  /**
   * SNS composite: parse SNS envelope then base64-decode then gunzip then parse. Same no-signature
   * posture as {@link #parseSqs(String)}.
   */
  public static Object parseSns(String notificationBody) throws InvalidWebhookError {
    return parseEvent(decodeSnsPayload(notificationBody));
  }

  private static String bytesToHex(byte[] bytes) {
    StringBuilder sb = new StringBuilder();
    for (byte b : bytes) {
      sb.append(String.format("%02x", b));
    }
    return sb.toString();
  }
}