Webhooks

Complete guide to how authentication transactions work in SendAuth

SendAuth supports webhooks to notify external services when approval events occur. Webhooks allow your applications to react to approval status changes in real-time, enabling integration with external systems, logging platforms, or custom workflow automation.

Overview

SendAuth offers two types of webhooks:

Global Webhooks - Fire for all approval events across the entire organization
Approval Group-Specific Webhooks - Fire only for approval events related to a specific approval group

Both webhook types can be configured to respond to specific events and include detailed payload information about the approval or transaction.

Webhook Events

Webhooks can be configured to fire on the following events:

Verify Events

Trigger: When an approval is successfully verified/approved
Use Case: Notify systems when access has been granted, trigger provisioning workflows, log successful approvals

Deny Events

Trigger: When an approval is denied/rejected
Use Case: Alert security teams, log access denials, trigger alternative workflows

Global Webhooks

Global webhooks are organization-wide and fire for approval events across all approval groups. They are ideal for:

Centralized logging and monitoring
Organization-wide security alerts
Cross-system integration that needs visibility into all approval activity

Managing Global Webhooks

Global webhooks are managed from the main Settings page:

Navigate to Settings in the main navigation
Click the Hooks tab
Configure your global webhooks using the interface

Global Webhook Behavior

Fire for all approval events in the organization
Include full approval and transaction context in payloads
Useful for organization-wide monitoring and integration

Approval Group-Specific Webhooks

Approval group-specific webhooks fire only for approval events related to a particular approval group. They are ideal for:

Department-specific integrations
Targeted notifications for sensitive approval groups
Granular control over which events trigger webhooks

Managing Approval Group Webhooks

Approval group webhooks are managed from within each approval group’s configuration:

Navigate to an Approval Group
Click the Webhooks tab
Configure webhooks specific to that approval group

Approval Group Webhook Behavior

Fire only for approval events within the specific approval group
Include the same detailed payload as global webhooks
Allow fine-grained control over webhook scope

Configuration

Required Fields

URL: The endpoint where webhook payloads will be sent

Must be a valid HTTPS URL
Maximum length: 2048 characters
SendAuth will POST JSON payloads to this URL

Optional Fields

Secret: A secret key used for payload signature verification

Used to generate an X-SendAuth-Signature header
Helps verify that webhook calls are coming from SendAuth
Recommended for production environments

Event Selection: Choose which events should trigger the webhook

Verify: Fires when approvals are successfully verified/approved
Deny: Fires when approvals are denied/rejected
You can select one or both events per webhook

When testing, the public service webhook.site can be helpful to verify the webhooks are correctly configured.

Payloads

Approval Payload Structure

When a webhook fires for an approval event, the payload includes:

{
  "id": "approval-uuid",
  "state": "verified|denied",
  "authGroup": {
    "id": "auth-group-uuid", 
    "name": "Approval Group Name",
    "threshold": "approval threshold",
    "description": "Approval group description"
  },
  "requestor": "user@example.com",
  "context": "approval context description",
  "createdAt": "2024-01-15T10:30:00Z",
  "completedAt": "2024-01-15T10:35:00Z", 
  "message": "approval message",
  "tags": {
    "environment": "production",
    "department": "engineering" 
  },
  "transactions": [
    {
      "id": "transaction-uuid",
      "subject": "user-uuid",
      "subjectName": "User Name",
      "state": "verified|denied",
      "completedAt": "2024-01-15T10:35:00Z",
      "requestor": "requester@example.com",
      "context": "transaction context",
      "createdAt": "2024-01-15T10:30:00Z",
      "expiresAt": "2024-01-15T11:30:00Z",
      "message": "transaction message",
      "userMessage": "message for end user",
      "tags": {
        "resource": "database",
        "action": "read"
      }
    }
  ],
  "payload": {
    "custom": "data",
    "additional": "context"
  }
}

Transaction Payload Structure

For transaction-specific webhooks (global webhooks), the payload includes individual transaction details:

{
  "id": "transaction-uuid",
  "subject": "user-uuid", 
  "subjectName": "User Name",
  "state": "verified|denied|pending|expired",
  "completedAt": "2024-01-15T10:35:00Z",
  "requestor": "requester@example.com", 
  "context": "transaction context description",
  "createdAt": "2024-01-15T10:30:00Z",
  "expiresAt": "2024-01-15T11:30:00Z",
  "message": "transaction message",
  "userMessage": "user-facing message",
  "host": "api.example.com",
  "tags": {
    "environment": "production",
    "resource": "database"
  },
  "approvalID": "related-approval-uuid"
}

Security

To verify the integrity of the message, you can set a Secret on the webhook. When the secret is set, SendAuth will send a checksum as SHA256(secret + payload) and send it in an HTTP header named x-sendauth-signature.

Knowing the secret on the webhook receiver side, you can construct the same hash and compare it.

This Go code snippet would print the checksum to STDOUT:

digest := sha256.New()
digest.Write([]byte(os.Getenv("SECRET")))
digest.Write(payloadBytes)
fmt.Printf("%x", digest.Sum(nil))

Webhook Status Monitoring

SendAuth tracks the status of webhook deliveries and displays this information in the UI:

Status Values

pending: Webhook has not yet been invoked
success: Last webhook delivery was successful (HTTP 2xx response)
error: Last webhook delivery failed (network error or non-2xx response)

Status Messages

Detailed status messages provide additional context:

“not yet invoked”: For new webhooks that haven’t fired
“status code: 200”: Successful delivery with response code
“unexpected status code: 404”: Failed delivery with HTTP error
Network error details: For connection failures

Best Practices

Endpoint Design

Ensure your webhook endpoints can handle POST requests
Return HTTP 2xx status codes for successful processing
Implement proper error handling and logging
Use idempotent processing in case of duplicate deliveries

Security

Always configure webhook secrets in production
Verify the X-SendAuth-Signature header in your endpoints
Use HTTPS for all webhook URLs
Implement rate limiting and abuse protection

Performance

Respond quickly to webhook requests (< 10 seconds recommended)
Process webhook payloads asynchronously when possible
Implement retry logic for failed external API calls

Troubleshooting

Common Issues

Webhook showing “error” status:

Check that your endpoint returns HTTP 2xx status codes
Verify your endpoint is accessible from SendAuth servers
Ensure your endpoint accepts POST requests with JSON payloads

Missing webhook deliveries:

Verify event configuration (verify/deny settings)
Check that the approval group has active approvals
Confirm webhook URL is correct and accessible

Authentication failures:

Verify the webhook secret configuration
Check signature verification logic in your endpoint
Ensure you’re using the correct signature algorithm (SHA256)

Getting Help

If you continue to experience issues with webhooks:

Check the webhook status messages in the UI for specific error details
Review your endpoint logs for incoming requests and responses
Test your webhook endpoint independently to verify it’s working
Contact support with specific error messages and webhook configuration details