Avnology ID
SDKsTypeScript SDKAdmin API

Webhook Management

Create, test, and manage webhook endpoints and delivery logs with the TypeScript SDK.

Webhook Management

Configure webhook endpoints to receive real-time notifications when events occur in Avnology ID (user created, session started, organization updated, etc.).

createWebhook()

Register a new webhook endpoint.

client.admin.createWebhook(params: CreateWebhookParams): Promise<Webhook>

Parameters

NameTypeRequiredDescription
urlstringyesHTTPS endpoint URL
eventsstring[]yesEvent types to subscribe to
organizationIdstringnoScope to a specific organization
secretstringnoSigning secret (auto-generated if omitted)
activebooleannoEnable immediately (default: true)
metadataRecord<string, string>noCustom metadata

Event types

EventDescription
user.createdNew user registered
user.updatedUser profile changed
user.deletedUser account deleted
session.createdNew session started
session.revokedSession ended
organization.createdNew organization
organization.updatedOrganization settings changed
organization.member.addedUser added to organization
organization.member.removedUser removed from organization
oauth.consent.grantedOAuth consent approved
oauth.consent.revokedOAuth consent revoked
mfa.enrolledMFA method added
mfa.removedMFA method removed
sso.connection.createdSSO connection configured
directory.sync.completedSCIM directory sync finished

Basic usage

const webhook = await client.admin.createWebhook({
  url: "https://myapp.com/webhooks/avnology",
  events: ["user.created", "user.updated", "user.deleted"],
});

console.log(webhook.id);     // "wh_abc123"
console.log(webhook.secret); // "whsec_..." (save this for verification)

testWebhook()

Send a test event to verify your endpoint is working.

const result = await client.admin.testWebhook({
  webhookId: "wh_abc123",
});

console.log(result.statusCode);  // 200
console.log(result.responseBody); // "OK"
console.log(result.durationMs);  // 145

listDeliveries()

View the delivery log for a webhook.

const deliveries = await client.admin.listWebhookDeliveries({
  webhookId: "wh_abc123",
  pageSize: 25,
});

for (const delivery of deliveries.deliveries) {
  console.log(delivery.id, delivery.event, delivery.status, delivery.statusCode);
  // "del_abc123" "user.created" "success" 200
  // "del_def456" "user.updated" "failed" 500
}

replayDelivery()

Retry a failed webhook delivery.

await client.admin.replayWebhookDelivery({
  webhookId: "wh_abc123",
  deliveryId: "del_def456",
});

rotateSecret()

Rotate the webhook signing secret with a grace period.

const result = await client.admin.rotateWebhookSecret({
  webhookId: "wh_abc123",
  gracePeriodHours: 24,
});

console.log("New secret:", result.secret);
console.log("Old secret valid for 24 more hours.");

Common errors

Error classHTTP statusWhen
NotFoundError404Webhook not found
ValidationError422Invalid URL or events
ForbiddenError403Insufficient permissions

See also

Service Accounts

Manage service accounts and API keys for machine-to-machine authentication with the TypeScript SDK.

Group Management

Create and manage static and dynamic groups with the TypeScript SDK.

On this page

Webhook ManagementcreateWebhook()ParametersEvent typesBasic usagetestWebhook()listDeliveries()replayDelivery()rotateSecret()Common errorsSee also