X Enterprises
fastify-xplaid

webhooks.update(accessToken, webhookUrl)

Update the webhook URL for a Plaid Item.

webhooks.update(accessToken, webhookUrl)

Registers a new webhook URL on an existing Plaid Item. Plaid will send TRANSACTIONS, ITEM, AUTH, and other event notifications to this URL. The URL must be publicly reachable and, in production, must use HTTPS.

Signature

fastify.xplaid.webhooks.update(
  accessToken: string,
  webhookUrl: string
): Promise<{ item: PlaidItem; requestId: string }>

Params

NameTypeRequiredDescription
accessTokenstringYesThe Item's permanent access token.
webhookUrlstringYesThe new webhook endpoint URL. Must be HTTPS in production.

Returns

Promise<{ item: PlaidItem, requestId: string }>

The returned item reflects the updated configuration, including the new webhook field.

Throws

  • [xPlaid] accessToken is required and must be a non-empty string
  • [xPlaid] webhookUrl is required and must be a non-empty string
  • Plaid API errors — shape: { message, statusCode, plaidError }.

Examples

Basic — register a webhook

const { item } = await fastify.xplaid.webhooks.update(
  accessToken,
  "https://api.example.com/webhooks/plaid"
);
console.log(item.webhook); // "https://api.example.com/webhooks/plaid"

Realistic — update webhook after an environment change

fastify.post("/admin/plaid/update-webhook", async (request, reply) => {
  const { newWebhookUrl } = request.body;
  const items = await db.plaidItems.findMany();

  const results = await Promise.allSettled(
    items.map(async (record) => {
      const { item } = await fastify.xplaid.webhooks.update(
        decrypt(record.accessToken),
        newWebhookUrl
      );
      await db.plaidItems.update({
        where: { id: record.id },
        data: { webhook: item.webhook },
      });
      return { itemId: record.itemId, webhook: item.webhook };
    })
  );

  const failed = results.filter((r) => r.status === "rejected");
  if (failed.length > 0) {
    request.log.error({ count: failed.length }, "Some webhook updates failed");
  }

  return {
    updated: results.filter((r) => r.status === "fulfilled").length,
    failed: failed.length,
  };
});

See also

AI Context

package: "@xenterprises/fastify-xplaid"
method: fastify.xplaid.webhooks.update(accessToken, webhookUrl)
use-when: Register or change the webhook URL that Plaid calls for Item events (TRANSACTIONS, ITEM, AUTH, etc.)
returns: { item, requestId }

webhooks.getVerificationKey(keyId)

Retrieve the JWK used to validate Plaid webhook payload signatures.

fastify-xrcs

Fastify plugin for building and sending RCS rich cards and carousels via Twilio's Content API, with a fluent builder pattern and optional builder-only mode.

Copyright © 2026