Mercury.Webhooks (mercury_client v1.0.0)

Copy Markdown View Source

The Mercury Webhooks API — registering endpoints, and verifying inbound webhook delivery signatures.

Summary

Functions

create(client, attrs)

Registers a new webhook endpoint. attrs accepts snake_case keys, e.g.

create!(client, attrs)
delete(client, webhook_id)

Deletes a webhook endpoint. DELETE /webhooks/{id}

delete!(client, webhook_id)
get(client, webhook_id)

Returns a single webhook by ID. GET /webhooks/{id}

get!(client, webhook_id)
list(client, opts \\ [])

Returns one page of webhooks. GET /webhooks

list!(client, opts \\ [])
stream(client, opts \\ [])

A lazy, auto-paginating stream of every webhook.

update(client, webhook_id, attrs)

Updates a webhook. Setting status: :active reactivates a disabled webhook. PUT /webhooks/{id}

update!(client, webhook_id, attrs)
verify(client, webhook_id, attrs \\ %{})

Sends a test event to the webhook endpoint. POST /webhooks/{id}/verify

verify!(client, webhook_id, attrs \\ %{})
verify_signature(raw_body, signature, signing_secret)

Verifies the signature on an inbound webhook delivery using constant-time HMAC-SHA256 comparison.

Functions

create(client, attrs)

@spec create(client :: Mercury.Client.t(), attrs :: map() | keyword()) ::
  {:ok, Mercury.Webhook.t()} | {:error, Exception.t()}

Registers a new webhook endpoint. attrs accepts snake_case keys, e.g.:

Mercury.Webhooks.create(client, %{
  url: "https://example.com/webhooks/mercury",
  event_types: ["transaction.created", "transaction.updated"]
})

POST /webhooks

create!(client, attrs)

@spec create!(client :: Mercury.Client.t(), attrs :: map() | keyword()) ::
  Mercury.Webhook.t()

delete(client, webhook_id)

@spec delete(client :: Mercury.Client.t(), webhook_id :: String.t()) ::
  :ok | {:error, Exception.t()}

Deletes a webhook endpoint. DELETE /webhooks/{id}

delete!(client, webhook_id)

@spec delete!(client :: Mercury.Client.t(), webhook_id :: String.t()) :: :ok

get(client, webhook_id)

@spec get(client :: Mercury.Client.t(), webhook_id :: String.t()) ::
  {:ok, Mercury.Webhook.t()} | {:error, Exception.t()}

Returns a single webhook by ID. GET /webhooks/{id}

get!(client, webhook_id)

@spec get!(client :: Mercury.Client.t(), webhook_id :: String.t()) ::
  Mercury.Webhook.t()

list(client, opts \\ [])

@spec list(client :: Mercury.Client.t(), opts :: keyword()) ::
  {:ok, Mercury.Page.t(Mercury.Webhook.t())} | {:error, Exception.t()}

Returns one page of webhooks. GET /webhooks

Accepts an :event_type filter in addition to the common list options.

list!(client, opts \\ [])

@spec list!(client :: Mercury.Client.t(), opts :: keyword()) ::
  Mercury.Page.t(Mercury.Webhook.t())

stream(client, opts \\ [])

@spec stream(client :: Mercury.Client.t(), opts :: keyword()) :: Enumerable.t()

A lazy, auto-paginating stream of every webhook.

update(client, webhook_id, attrs)

@spec update(
  client :: Mercury.Client.t(),
  webhook_id :: String.t(),
  attrs :: map() | keyword()
) ::
  {:ok, Mercury.Webhook.t()} | {:error, Exception.t()}

Updates a webhook. Setting status: :active reactivates a disabled webhook. PUT /webhooks/{id}

update!(client, webhook_id, attrs)

@spec update!(
  client :: Mercury.Client.t(),
  webhook_id :: String.t(),
  attrs :: map() | keyword()
) ::
  Mercury.Webhook.t()

verify(client, webhook_id, attrs \\ %{})

@spec verify(
  client :: Mercury.Client.t(),
  webhook_id :: String.t(),
  attrs :: map() | keyword()
) ::
  :ok | {:error, Exception.t()}

Sends a test event to the webhook endpoint. POST /webhooks/{id}/verify

verify!(client, webhook_id, attrs \\ %{})

@spec verify!(
  client :: Mercury.Client.t(),
  webhook_id :: String.t(),
  attrs :: map() | keyword()
) :: :ok

verify_signature(raw_body, signature, signing_secret)

@spec verify_signature(
  raw_body :: binary(),
  signature :: String.t(),
  signing_secret :: String.t()
) :: boolean()

Verifies the signature on an inbound webhook delivery using constant-time HMAC-SHA256 comparison.

Confirm the signing scheme first

The reference Go SDK does not implement inbound signature verification, so this assumes the common convention of a hex-encoded HMAC-SHA256(raw_request_body, signing_secret) digest sent in a header. Confirm the exact header name and encoding against the current Mercury webhooks documentation for your endpoint before relying on this in production — providers sometimes use a composite header (e.g. t=<timestamp>,v1=<digest>) instead of a bare digest, in which case extract the digest yourself and pass it as signature.

raw_body must be the raw, unparsed request body bytes — signatures will not match against a re-encoded/re-serialized payload.

Examples

Mercury.Webhooks.verify_signature(raw_body, signature_header, signing_secret)
#=> true | false