Marqeta.Webhooks (marqeta v1.0.0)

Create and manage webhook endpoints for real-time event notifications.

Marqeta sends HTTPS POST requests to your endpoint when events occur.

Authentication options

HTTP Basic Auth: config.basic_auth_username + config.basic_auth_password
HMAC Signature: config.secret + config.signature_algorithm (HMAC_SHA_256 or HMAC_SHA_1)
mTLS (beta): mutual TLS via certificate

Event wildcard syntax

"*" — all events
"transaction.*" — all transaction events
Wildcards work only on top-level types; "cardtransition.fulfillment.*" is NOT valid.

See Marqeta.EventTypes for all available event strings.

Example

{:ok, webhook} = Marqeta.Webhooks.create(%{
  name: "production",
  active: true,
  events: ["*"],
  config: %{
    url: "https://api.yourapp.com/webhooks/marqeta",
    basic_auth_username: "webhook_user",
    basic_auth_password: "S3cur3P@ssw0rd!XY",
    secret: "MyHmacSecret@123456789",
    signature_algorithm: "HMAC_SHA_256",
    custom_header: %{"X-My-Token" => "abc123"}
  }
})

# Test connectivity
{:ok, _} = Marqeta.Webhooks.ping(webhook["token"])

# Resend a specific event
{:ok, _} = Marqeta.Webhooks.resend(webhook["token"], "event_token_abc")

Summary

Functions

create(params \\ %{}, opts \\ [])

Creates a new webhook.

create!(params \\ %{}, opts \\ [])

Creates a new webhook. Raises Marqeta.Error on failure.

event_type(arg1)

Extracts the event type from a parsed webhook event.

get(token, opts \\ [])

Retrieves a webhook by token.

get!(token, opts \\ [])

Retrieves a webhook by token. Raises Marqeta.Error on failure.

list(params \\ %{}, opts \\ [])

Lists webhook resources.

list!(params \\ %{}, opts \\ [])

Lists webhook resources. Raises Marqeta.Error on failure.

parse_event(body)

Parses an incoming webhook event body.

ping(webhook_token, opts \\ [])

Sends a ping to test that your webhook endpoint is reachable.

resend(webhook_token, event_token, opts \\ [])

Resends a specific event notification to the webhook endpoint.

stream(params \\ %{}, opts \\ [])

Returns a lazy Stream that auto-paginates webhook resources.

update(token, params, opts \\ [])

Updates an existing webhook.

update!(token, params, opts \\ [])

Updates an existing webhook. Raises Marqeta.Error on failure.

valid_signature?(payload, signature, secret)

Verifies an incoming webhook payload against its HMAC-SHA256 signature.

valid_signature_sha1?(payload, signature, secret)

Verifies an HMAC-SHA1 signature (for webhooks using HMAC_SHA_1). Prefer SHA-256 for new integrations.

Functions

create(params \\ %{}, opts \\ [])

@spec create(
  map(),
  keyword()
) :: {:ok, map()} | {:error, Marqeta.Error.t()}

Creates a new webhook.

Returns {:ok, map()} on success, {:error, %Marqeta.Error{}} on failure.

create!(params \\ %{}, opts \\ [])

@spec create!(
  map(),
  keyword()
) :: map()

Creates a new webhook. Raises Marqeta.Error on failure.

event_type(arg1)

@spec event_type(map()) :: String.t() | nil

Extracts the event type from a parsed webhook event.

Examples

{:ok, event} = Marqeta.Webhooks.parse_event(body)
Marqeta.Webhooks.event_type(event)
# => "transaction.authorization"

get(token, opts \\ [])

@spec get(
  String.t(),
  keyword()
) :: {:ok, map()} | {:error, Marqeta.Error.t()}

Retrieves a webhook by token.

Returns {:ok, map()} on success, {:error, %Marqeta.Error{}} on failure.

get!(token, opts \\ [])

@spec get!(
  String.t(),
  keyword()
) :: map()

Retrieves a webhook by token. Raises Marqeta.Error on failure.

list(params \\ %{}, opts \\ [])

@spec list(
  map(),
  keyword()
) :: {:ok, map()} | {:error, Marqeta.Error.t()}

Lists webhook resources.

Accepts standard Marqeta pagination params: count, start_index, sort_by, sort_order, fields.

Use stream/2 to lazily iterate all pages automatically.

list!(params \\ %{}, opts \\ [])

@spec list!(
  map(),
  keyword()
) :: map()

Lists webhook resources. Raises Marqeta.Error on failure.

parse_event(body)

@spec parse_event(String.t() | map()) ::
  {:ok, map()} | {:error, Jason.DecodeError.t()}

Parses an incoming webhook event body.

Returns

{:ok, event_map} or {:error, decode_error}.

ping(webhook_token, opts \\ [])

@spec ping(
  String.t(),
  keyword()
) :: {:ok, map()} | {:error, Marqeta.Error.t()}

Sends a ping to test that your webhook endpoint is reachable.

resend(webhook_token, event_token, opts \\ [])

@spec resend(String.t(), String.t(), keyword()) ::
  {:ok, map()} | {:error, Marqeta.Error.t()}

Resends a specific event notification to the webhook endpoint.

stream(params \\ %{}, opts \\ [])

@spec stream(
  map(),
  keyword()
) :: Enumerable.t()

Returns a lazy Stream that auto-paginates webhook resources.

update(token, params, opts \\ [])

@spec update(String.t(), map(), keyword()) ::
  {:ok, map()} | {:error, Marqeta.Error.t()}

Updates an existing webhook.

Returns {:ok, map()} on success, {:error, %Marqeta.Error{}} on failure.

update!(token, params, opts \\ [])

@spec update!(String.t(), map(), keyword()) :: map()

Updates an existing webhook. Raises Marqeta.Error on failure.

valid_signature?(payload, signature, secret)

@spec valid_signature?(binary(), String.t(), String.t()) :: boolean()

Verifies an incoming webhook payload against its HMAC-SHA256 signature.

Always verify signatures in production to prevent spoofed webhook delivery.

Parameters

payload — Raw request body binary (do NOT parse JSON first)
signature — Value from X-Marqeta-Signature header
secret — Your webhook secret configured in config.secret

Returns

true if the signature is valid, false otherwise.

Phoenix example

defmodule MyAppWeb.MarqetaWebhookController do
  use MyAppWeb, :controller

  def handle(conn, _params) do
    sig    = get_req_header(conn, "x-marqeta-signature") |> List.first("")
    body   = conn.assigns[:raw_body]
    secret = Application.fetch_env!(:my_app, :marqeta_webhook_secret)

    if Marqeta.Webhooks.valid_signature?(body, sig, secret) do
      process_event(conn.body_params)
      send_resp(conn, 200, "ok")
    else
      send_resp(conn, 401, "invalid signature")
    end
  end
end

valid_signature_sha1?(payload, signature, secret)

@spec valid_signature_sha1?(binary(), String.t(), String.t()) :: boolean()

Verifies an HMAC-SHA1 signature (for webhooks using HMAC_SHA_1). Prefer SHA-256 for new integrations.