Webhooks

Authpipe supports webhooks in two directions:

• Outbound — Authpipe sends events to your app (connection created, token refreshed, refresh failed, etc.)
• Inbound — External providers send webhooks to Authpipe, which verifies and forwards them

Outbound webhooks (Authpipe to your app)

Set up a webhook URL

Node

const result = await authpipe.setWebhookConfig("https://yourapp.com/webhooks/authpipe");

console.log(result.webhook_url); // "https://yourapp.com/webhooks/authpipe"
console.log(result.secret);      // "whsec_..." — save this securely

Go

result, err := client.SetWebhookConfig(ctx, &authpipe.SetWebhookConfigParams{
  WebhookURL: "https://yourapp.com/webhooks/authpipe",
})
// result.Secret — save this securely

Python

result = client.set_webhook_config(
    webhook_url="https://yourapp.com/webhooks/authpipe",
)
# result.secret — save this securely

The response includes a secret for signature verification. Store it securely — it’s only returned once.

Event types

Event	Trigger
installation.created	App installed in external workspace
installation.updated	Permissions or tokens changed
installation.suspended	Installation paused by provider
installation.deleted	Installation removed
connection.created	User completes OAuth or credential stored
connection.refreshed	Token silently refreshed
connection.failed	Refresh or health check failed
connection.revoked	User or admin disconnected
connection.reauth_required	Token expired, needs user action
connection.scopes_changed	Granted scopes modified
connection.deleted	Connection permanently removed
credential.stored	New credential encrypted and saved
credential.rotated	Credential rotated (API key, webhook secret)
webhook.received	Inbound provider webhook verified and processed

Verify webhook signatures

Authpipe signs outbound webhooks with HMAC-SHA256. Verify the signature using the secret from setWebhookConfig.

import crypto from "crypto";

function verifyWebhookSignature(
  payload: string,
  signature: string,
  secret: string,
): boolean {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(payload)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected),
  );
}

// In your webhook handler:
app.post("/webhooks/authpipe", (req, res) => {
  const signature = req.headers["x-authpipe-signature"];
  if (!verifyWebhookSignature(req.rawBody, signature, WEBHOOK_SECRET)) {
    return res.status(401).send("Invalid signature");
  }

  const event = req.body;
  switch (event.event_type) {
    case "connection.created":
      console.log("New connection:", event.data);
      break;
    case "connection.failed":
      console.log("Connection needs attention:", event.data);
      break;
  }
  res.status(200).send("OK");
});

Rotate secrets

Rotate the signing secret without downtime. After rotation, Authpipe supports both the old and new secrets during the transition.

Node

const result = await authpipe.rotateWebhookSecret();
console.log(result.secret); // new secret — update your app

Go

result, err := client.RotateWebhookSecret(ctx)
// result.Secret — the new signing secret

Python

result = client.rotate_webhook_secret()
# result.secret — the new signing secret

After rotation:

• secret_1 = new secret (current)
• secret_2 = old secret (still valid for verification)

Update your app to use the new secret, then both secrets will be valid until the next rotation.

Check webhook config

Node

const config = await authpipe.getWebhookConfig();
console.log(config.webhook_url);  // your URL
console.log(config.has_secret_1); // true
console.log(config.has_secret_2); // true (if rotated at least once)

Go

config, err := client.GetWebhookConfig(ctx)

Python

config = client.get_webhook_config()

Delete webhook config

Node

await authpipe.deleteWebhookConfig();

Go

err := client.DeleteWebhookConfig(ctx)

Python

client.delete_webhook_config()

Inbound webhooks (provider to Authpipe)

Some providers send webhooks to Authpipe (e.g., Slack events, GitHub webhooks). These arrive at:

POST https://api.authpipe.dev/webhooks/{provider}

Authpipe verifies the webhook signature using the signing_key on the provider config, processes the event, and emits a webhook.received event to your outbound webhook URL.

Configure a signing key

Set the provider’s signing/verification key on your provider config:

Node

await authpipe.updateProviderConfig("pcfg_abc123", {
  signing_key: "your-provider-signing-secret",
});

Go

_, err := client.UpdateProviderConfig(ctx, "pcfg_abc123", &authpipe.UpdateProviderConfigParams{
  SigningKey: "your-provider-signing-secret",
})

Python

client.update_provider_config(
    config_id="pcfg_abc123",
    signing_key="your-provider-signing-secret",
)

Searching events

Query the event log to audit webhook delivery and credential lifecycle events.

Node

const events = await authpipe.searchEvents({
  filter: {
    event_type: { eq: "connection.failed" },
  },
  sort: [{ field: "created_at", direction: "desc" }],
  limit: 20,
});

Go

resp, err := client.SearchEvents(ctx, &authpipe.SearchRequest{
  Filter: map[string]map[string]interface{}{
    "event_type": {"eq": "connection.failed"},
  },
  Sort:  []authpipe.SortDirective{{Field: "created_at", Direction: "desc"}},
  Limit: 20,
})

Python

from authpipe.types import SearchRequest, SortDirective

resp = client.search_events(SearchRequest(
    filter={"event_type": {"eq": "connection.failed"}},
    sort=[SortDirective(field="created_at", direction="desc")],
    limit=20,
))