PlaidEx.Webhooks.Handler behaviour (plaid_ex v1.0.0)

Copy Markdown View Source

Behaviour for Plaid webhook handlers.

Implement this in your application to receive typed webhook events. All callbacks are optional — unimplemented ones fall through to on_unknown/1 which has a default no-op implementation.

Example

defmodule MyApp.PlaidWebhooks do
  @behaviour PlaidEx.Webhooks.Handler

  @impl true
  def on_transactions_sync(%{item_id: item_id}) do
    # Triggered by TRANSACTIONS.SYNC_UPDATES_AVAILABLE
    # Trigger your sync worker to fetch new data
    PlaidEx.Sync.TransactionSync.trigger_sync(
      MyApp.Items.get_access_token!(item_id)
    )
    :ok
  end

  @impl true
  def on_item_error(%{item_id: item_id, error: error}) do
    case error["error_code"] do
      "ITEM_LOGIN_REQUIRED" ->
        MyApp.Users.notify_reconnect_required(item_id)
      _ ->
        MyApp.Alerts.notify_item_error(item_id, error)
    end
    :ok
  end

  @impl true
  def on_item_pending_expiration(%{item_id: item_id}) do
    # Item will expire in 7 days — notify user to reconnect
    MyApp.Users.notify_expiring_connection(item_id)
    :ok
  end

  @impl true
  def on_transfer_events_update(_event) do
    MyApp.Transfers.sync_events()
    :ok
  end

  # Catch-all for events you haven't handled yet
  @impl true
  def on_unknown(event) do
    require Logger
    Logger.debug("[PlaidWebhooks] Unhandled: #{inspect(event)}")
    :ok
  end
end

Summary

Types

event()
result()

Callbacks

on_assets_error(event)
on_assets_product_ready(event)
on_auth_automatically_verified(event)
on_auth_verification_expired(event)
on_beacon_user_review_status_updated(event)
on_identity_verification_retried(event)
on_identity_verification_status_updated(event)
on_income_verification(event)
on_investments_default_update(event)
on_item_error(event)
on_item_new_accounts(event)
on_item_pending_expiration(event)
on_item_permission_revoked(event)
on_liabilities_default_update(event)
on_payment_status_update(event)
on_signal_default_update(event)
on_statements_ready(event)
on_transactions_default_update(event)
on_transactions_historical_update(event)
on_transactions_initial_update(event)
on_transactions_sync(event)
on_transfer_events_update(event)
on_unknown(event)

Functions

__using__(_)

Injects default no-op implementations for all optional callbacks. Use this when you only want to handle a subset of events.

Types

event()

@type event() :: map() | struct()

result()

@type result() :: :ok | {:error, term()}

Callbacks

on_assets_error(event)

(optional) 
@callback on_assets_error(event()) :: result()

on_assets_product_ready(event)

(optional) 
@callback on_assets_product_ready(event()) :: result()

on_auth_automatically_verified(event)

(optional) 
@callback on_auth_automatically_verified(event()) :: result()

on_auth_verification_expired(event)

(optional) 
@callback on_auth_verification_expired(event()) :: result()

on_beacon_user_review_status_updated(event)

(optional) 
@callback on_beacon_user_review_status_updated(event()) :: result()

on_identity_verification_retried(event)

(optional) 
@callback on_identity_verification_retried(event()) :: result()

on_identity_verification_status_updated(event)

(optional) 
@callback on_identity_verification_status_updated(event()) :: result()

on_income_verification(event)

(optional) 
@callback on_income_verification(event()) :: result()

on_investments_default_update(event)

(optional) 
@callback on_investments_default_update(event()) :: result()

on_item_error(event)

(optional) 
@callback on_item_error(event()) :: result()

on_item_new_accounts(event)

(optional) 
@callback on_item_new_accounts(event()) :: result()

on_item_pending_expiration(event)

(optional) 
@callback on_item_pending_expiration(event()) :: result()

on_item_permission_revoked(event)

(optional) 
@callback on_item_permission_revoked(event()) :: result()

on_liabilities_default_update(event)

(optional) 
@callback on_liabilities_default_update(event()) :: result()

on_payment_status_update(event)

(optional) 
@callback on_payment_status_update(event()) :: result()

on_signal_default_update(event)

(optional) 
@callback on_signal_default_update(event()) :: result()

on_statements_ready(event)

(optional) 
@callback on_statements_ready(event()) :: result()

on_transactions_default_update(event)

(optional) 
@callback on_transactions_default_update(event()) :: result()

on_transactions_historical_update(event)

(optional) 
@callback on_transactions_historical_update(event()) :: result()

on_transactions_initial_update(event)

(optional) 
@callback on_transactions_initial_update(event()) :: result()

on_transactions_sync(event)

(optional) 
@callback on_transactions_sync(event()) :: result()

on_transfer_events_update(event)

(optional) 
@callback on_transfer_events_update(event()) :: result()

on_unknown(event)

(optional) 
@callback on_unknown(event()) :: result()

Functions

__using__(_)

(macro)

Injects default no-op implementations for all optional callbacks. Use this when you only want to handle a subset of events.

defmodule MyApp.PlaidWebhooks do
  use PlaidEx.Webhooks.Handler

  @impl true
  def on_transactions_sync(event) do
    # Only this one is custom — all others are no-ops
    trigger_my_sync(event.item_id)
    :ok
  end
end