Configure webhook endpoints to receive real-time notifications for all 31 Authsome events, with HMAC signing and Relay bridge integration.
Authsome delivers event notifications to your own HTTP endpoints via webhooks. Every significant event -- user creation, sign-in attempts, MFA enrollment, organization changes, environment lifecycle -- fires a webhook. You can configure multiple endpoints and subscribe each one to different event types.
import "github.com/xraph/authsome/webhook"result, err := auth.Webhooks().Create(ctx, &webhook.CreateInput{ Name: "My Backend Notifications", URL: "https://api.myapp.com/authsome/events", Events: []string{ "user.created", "user.deleted", "auth.signin", "auth.signin.failed", "session.revoked", }, Headers: map[string]string{ "X-Source": "authsome", }, MaxRetries: 3, TimeoutMs: 5000,})if err != nil { return err}// result.Secret is the signing secret -- only available at creation time.fmt.Printf("webhook created: id=%s secret=%s\n", result.Webhook.ID, result.Secret)
The webhook signing secret is returned only once at creation time and is not stored in plain text. Store it securely (e.g., in your secrets manager). If you lose it, rotate it using auth.Webhooks().RotateSecret(ctx, webhookID).
// List all webhooks.result, err := auth.Webhooks().List(ctx, &webhook.ListInput{Limit: 50})// Get a specific webhook.w, err := auth.Webhooks().GetByID(ctx, webhookID)// Update a webhook (e.g., change subscribed events).updated, err := auth.Webhooks().Update(ctx, webhookID, &webhook.UpdateInput{ Events: []string{"user.created", "user.deleted"}, IsActive: true,})// Deactivate (pause delivery without deleting).err := auth.Webhooks().Deactivate(ctx, webhookID)// Delete permanently.err := auth.Webhooks().Delete(ctx, webhookID)// Rotate the signing secret.result, err := auth.Webhooks().RotateSecret(ctx, webhookID)// result.NewSecret is the new secret -- only available here.
Every webhook request includes an X-Authsome-Signature header containing an HMAC-SHA256 signature of the raw request body. Verify this signature on your endpoint before processing the payload:
package webhookhandlerimport ( "crypto/hmac" "crypto/sha256" "encoding/hex" "io" "net/http")func HandleAuthsomeWebhook(secret string) http.HandlerFunc { return func(w http.ResponseWriter, r *http.Request) { body, err := io.ReadAll(r.Body) if err != nil { http.Error(w, "cannot read body", http.StatusBadRequest) return } // Verify HMAC-SHA256 signature. sig := r.Header.Get("X-Authsome-Signature") mac := hmac.New(sha256.New, []byte(secret)) mac.Write(body) expected := "sha256=" + hex.EncodeToString(mac.Sum(nil)) if !hmac.Equal([]byte(sig), []byte(expected)) { http.Error(w, "invalid signature", http.StatusUnauthorized) return } // Process the verified payload. var payload map[string]any json.Unmarshal(body, &payload) // ... w.WriteHeader(http.StatusOK) }}
Relay is the Forge-ecosystem's event bus. When Relay is configured, Authsome publishes every event to Relay in addition to (or instead of) direct HTTP webhook delivery. This lets other services in your platform subscribe to authentication events without going through HTTP.