Fivetrex.Webhooks (Fivetrex v0.2.1)

View Source

Functions for managing Fivetran Webhooks.

Webhooks provide real-time notifications about Fivetran events such as sync starts, completions, and failures. This module supports creating, managing, and testing webhooks at both account and group levels.

Overview

Webhooks can be configured at two levels:

  • Account-level - Receives events for all connectors in your account
  • Group-level - Receives events only for connectors in a specific group

Common Operations

Listing Webhooks

{:ok, %{items: webhooks, next_cursor: cursor}} = Fivetrex.Webhooks.list(client)

Getting a Webhook

{:ok, webhook} = Fivetrex.Webhooks.get(client, "webhook_id")

Creating an Account Webhook

{:ok, webhook} = Fivetrex.Webhooks.create_account(client, %{
  url: "https://example.com/webhook",
  events: ["sync_start", "sync_end"],
  active: true,
  secret: "my_webhook_secret"
})

Creating a Group Webhook

{:ok, webhook} = Fivetrex.Webhooks.create_group(client, "group_id", %{
  url: "https://example.com/webhook",
  events: ["sync_end"],
  active: true
})

Testing a Webhook

{:ok, result} = Fivetrex.Webhooks.test(client, "webhook_id")

Streaming

For iterating over all webhooks without loading them into memory:

client
|> Fivetrex.Webhooks.stream()
|> Stream.filter(&Webhook.account_level?/1)
|> Enum.each(&IO.inspect/1)

Security

When creating webhooks with a secret, Fivetran signs each payload using HMAC-SHA256. Use Fivetrex.WebhookSignature.verify/3 to validate incoming requests in your webhook handler.

See Also

Summary

Functions

create_account(client, params)

Creates an account-level webhook.

create_group(client, group_id, params)

Creates a group-level webhook.

delete(client, webhook_id)

Deletes a webhook.

get(client, webhook_id)

Gets a webhook by its ID.

list(client, opts \\ [])

Lists all webhooks (both account and group level).

stream(client, opts \\ [])

Returns a stream of all webhooks, handling pagination automatically.

test(client, webhook_id, opts \\ [])

Sends a test event to a webhook.

update(client, webhook_id, params)

Updates an existing webhook.

Functions

create_account(client, params)

@spec create_account(Fivetrex.Client.t(), map()) ::
  {:ok, Fivetrex.Models.Webhook.t()} | {:error, Fivetrex.Error.t()}

Creates an account-level webhook.

Account webhooks receive events for all connectors in your Fivetran account.

Parameters

  • client - The Fivetrex client
  • params - A map with webhook parameters:
    • :url - Required. Endpoint URL for webhook delivery.
    • :events - Required. List of event types (e.g., ["sync_start", "sync_end"]).
    • :active - Optional. Whether webhook is active (default: true).
    • :secret - Optional. Secret for HMAC signature verification.

Returns

  • {:ok, Webhook.t()} - The created webhook
  • {:error, Fivetrex.Error.t()} - On failure

Examples

{:ok, webhook} = Fivetrex.Webhooks.create_account(client, %{
  url: "https://example.com/fivetran/webhook",
  events: ["sync_end"],
  active: true,
  secret: "my_secret_key"
})
IO.puts("Created webhook: #{webhook.id}")

create_group(client, group_id, params)

@spec create_group(Fivetrex.Client.t(), String.t(), map()) ::
  {:ok, Fivetrex.Models.Webhook.t()} | {:error, Fivetrex.Error.t()}

Creates a group-level webhook.

Group webhooks receive events only for connectors in the specified group.

Parameters

  • client - The Fivetrex client
  • group_id - The ID of the group to attach the webhook to
  • params - A map with webhook parameters (same as create_account/2):
    • :url - Required. Endpoint URL for webhook delivery.
    • :events - Required. List of event types.
    • :active - Optional. Whether webhook is active (default: true).
    • :secret - Optional. Secret for HMAC signature verification.

Returns

  • {:ok, Webhook.t()} - The created webhook
  • {:error, Fivetrex.Error.t()} - On failure

Examples

{:ok, webhook} = Fivetrex.Webhooks.create_group(client, "group_id", %{
  url: "https://example.com/fivetran/webhook",
  events: ["sync_start", "sync_end"],
  active: true
})
IO.puts("Created group webhook: #{webhook.id}")

delete(client, webhook_id)

@spec delete(Fivetrex.Client.t(), String.t()) :: :ok | {:error, Fivetrex.Error.t()}

Deletes a webhook.

Warning: This operation cannot be undone. The webhook will immediately stop receiving events.

Parameters

  • client - The Fivetrex client
  • webhook_id - The ID of the webhook to delete

Returns

  • :ok - On successful deletion
  • {:error, Fivetrex.Error.t()} - On failure

Examples

:ok = Fivetrex.Webhooks.delete(client, "webhook_id")

get(client, webhook_id)

@spec get(Fivetrex.Client.t(), String.t()) ::
  {:ok, Fivetrex.Models.Webhook.t()} | {:error, Fivetrex.Error.t()}

Gets a webhook by its ID.

Parameters

  • client - The Fivetrex client
  • webhook_id - The unique identifier of the webhook

Returns

  • {:ok, Webhook.t()} - The webhook as a %Fivetrex.Models.Webhook{} struct
  • {:error, Fivetrex.Error.t()} - On failure (e.g., :not_found if ID is invalid)

Examples

{:ok, webhook} = Fivetrex.Webhooks.get(client, "webhook_id")
IO.puts("Webhook URL: #{webhook.url}")

Handle not found:

case Fivetrex.Webhooks.get(client, "invalid_id") do
  {:ok, webhook} -> webhook
  {:error, %Fivetrex.Error{type: :not_found}} -> nil
end

list(client, opts \\ [])

@spec list(
  Fivetrex.Client.t(),
  keyword()
) ::
  {:ok, %{items: [Fivetrex.Models.Webhook.t()], next_cursor: String.t() | nil}}
  | {:error, Fivetrex.Error.t()}

Lists all webhooks (both account and group level).

Returns a paginated list of webhooks. Use the next_cursor from the response to fetch the next page, or use stream/2 for automatic pagination.

Options

  • :cursor - Pagination cursor from a previous response's next_cursor. Pass nil or omit for the first page.

  • :limit - Maximum number of webhooks to return per page. Maximum is 1000.

Returns

  • {:ok, %{items: [Webhook.t()], next_cursor: String.t() | nil}} - A map containing:

    • :items - List of %Fivetrex.Models.Webhook{} structs
    • :next_cursor - Cursor for the next page, or nil if this is the last page

  • {:error, Fivetrex.Error.t()} - On failure

Examples

Fetch the first page:

{:ok, %{items: webhooks, next_cursor: cursor}} = Fivetrex.Webhooks.list(client)

Fetch the next page using a cursor:

{:ok, %{items: more_webhooks, next_cursor: next}} =
  Fivetrex.Webhooks.list(client, cursor: cursor)

stream(client, opts \\ [])

@spec stream(
  Fivetrex.Client.t(),
  keyword()
) :: Enumerable.t()

Returns a stream of all webhooks, handling pagination automatically.

This function returns an Elixir Stream that lazily fetches pages as needed. It's memory-efficient for iterating over large numbers of webhooks.

Options

  • :limit - Number of items per page (passed to each API call)

Returns

An Enumerable.t() that yields %Fivetrex.Models.Webhook{} structs.

Examples

Stream all webhooks:

Fivetrex.Webhooks.stream(client)
|> Enum.each(fn webhook ->
  IO.puts("Webhook: #{webhook.id} -> #{webhook.url}")
end)

Filter by type:

account_webhooks =
  Fivetrex.Webhooks.stream(client)
  |> Stream.filter(&Webhook.account_level?/1)
  |> Enum.to_list()

Error Handling

If an API error occurs during streaming, a Fivetrex.Error is raised. Use try/rescue to handle errors:

try do
  Fivetrex.Webhooks.stream(client) |> Enum.to_list()
rescue
  e in Fivetrex.Error ->
    Logger.error("Failed: #{e.message}")
    []
end

test(client, webhook_id, opts \\ [])

@spec test(Fivetrex.Client.t(), String.t(), keyword()) ::
  {:ok, map()} | {:error, Fivetrex.Error.t()}

Sends a test event to a webhook.

Fivetran sends a test webhook with a dummy connection identifier _connection_1. Use this to verify your webhook endpoint is correctly configured and can receive events.

Parameters

  • client - The Fivetrex client
  • webhook_id - The ID of the webhook to test
  • opts - Optional keyword list:
    • :event - Specific event type to test (e.g., "sync_end")

Returns

  • {:ok, map()} - Test result from Fivetran
  • {:error, Fivetrex.Error.t()} - On failure

Examples

Send a default test event:

{:ok, result} = Fivetrex.Webhooks.test(client, "webhook_id")

Test a specific event type:

{:ok, result} = Fivetrex.Webhooks.test(client, "webhook_id", event: "sync_end")

update(client, webhook_id, params)

@spec update(Fivetrex.Client.t(), String.t(), map()) ::
  {:ok, Fivetrex.Models.Webhook.t()} | {:error, Fivetrex.Error.t()}

Updates an existing webhook.

Parameters

  • client - The Fivetrex client
  • webhook_id - The ID of the webhook to update
  • params - A map with fields to update:
    • :url - New endpoint URL
    • :events - Updated list of event types
    • :active - Enable/disable the webhook
    • :secret - New secret for signature verification

Returns

  • {:ok, Webhook.t()} - The updated webhook
  • {:error, Fivetrex.Error.t()} - On failure

Examples

{:ok, webhook} = Fivetrex.Webhooks.update(client, "webhook_id", %{
  active: false
})

{:ok, webhook} = Fivetrex.Webhooks.update(client, "webhook_id", %{
  events: ["sync_end", "sync_start"],
  url: "https://new-url.example.com/webhook"
})