Providers

Action providers are endpoints that execute workflow responses. Hydden Discovery supports multiple provider types for notifications and integrations. This topic covers email providers (SendGrid and SMTP). For other provider types, see ServiceNow, Webhook, and Add to Vault.

Overview

Email providers enable automated notifications via email when workflows are triggered. Hydden Discovery supports two email provider types:

• SendGrid: Cloud-based email delivery service using the SendGrid API
• SMTP: Direct connection to any SMTP-compliant email server

Prerequisites

Before configuring email providers:

• Credentials: Create a credential in Configuration > Settings > Credentials containing:
  • For SendGrid: API key stored in the password field
  • For SMTP: Username and password (or OAuth2 bearer token)
• Network Access: Ensure Hydden Discovery can reach:
  • SendGrid API: https://api.sendgrid.com
  • SMTP server: Your mail server's hostname and port
• Permissions: Verify service account has permission to send email

SendGrid Provider

Configuration

SendGrid providers use the SendGrid API for reliable, scalable email delivery.

To add a SendGrid provider:

1. In Hydden, navigate to Configuration > Automate.
2. On the Providers tab, click + Add New.
3. From the Type drop-down, select SendGrid.
4. For Name, enter a descriptive name (e.g., "SendGrid Production Alerts").
5. For Description, enter an optional description of the provider's purpose.
6. For From, enter the sender email address (e.g., noreply@hydden.com).
   • This address appears in the "From" field of sent emails
   • Must be a verified sender in your SendGrid account
7. From the Credential drop-down, select a previously configured credential containing your SendGrid API key.
   • The API key should be stored in the credential's password field
8. Click Save.

SendGrid Authentication

SendGrid providers authenticate using API keys:

• API Key: Stored in the credential password field
• Authentication Method: Bearer token authentication to SendGrid API
• Endpoint: https://api.sendgrid.com/v3/mail/send

SendGrid Best Practices

• Sender Verification: Verify sender email addresses in SendGrid to prevent delivery issues
• API Keys: Use dedicated API keys with "Mail Send" permission only (principle of least privilege)
• Rate Limits: SendGrid applies rate limits based on your plan - monitor usage if sending high volumes
• Bounce Handling: Configure bounce handling in SendGrid to manage undeliverable emails

SMTP Provider

Configuration

SMTP providers connect directly to any SMTP-compliant mail server, including Microsoft Exchange, Office 365, Gmail, and self-hosted mail servers.

To add an SMTP provider:

1. In Hydden, navigate to Configuration > Automate.
2. On the Providers tab, click + Add New.
3. From the Type drop-down, select SMTP.
4. For Name, enter a descriptive name (e.g., "Corporate Exchange Server").
5. For Description, enter an optional description of the provider's purpose.
6. For From, enter the sender email address (e.g., hydden-alerts@corp.example.com).
   • This address appears in the "From" field of sent emails
   • Must be a valid mailbox or authorized sender in your mail system
7. For SMTP Server, enter the mail server hostname (e.g., smtp.office365.com or mail.corp.local).
8. For Port, enter the SMTP port number:
   • 587: STARTTLS (recommended for most configurations)
   • 465: SMTP with TLS/SSL
   • 25: Unencrypted SMTP (not recommended for production)
9. From the Credential drop-down, select a previously configured credential containing:
   • Username: SMTP authentication username
   • Password: SMTP authentication password (or OAuth2 bearer token)
10. Click Save.

SMTP Authentication

SMTP providers support multiple authentication mechanisms:

Standard Authentication (PLAIN)

• Username/Password: Basic authentication using credentials
• Use Case: Most common for internal mail servers and Office 365
• Configuration: Store username and password in credential

OAuth2 Authentication (XOAUTH2)

• Bearer Token: OAuth2 access token for authentication
• Use Case: Gmail, Office 365 with modern authentication
• Configuration: Store OAuth2 access token in credential password field
• Auth Type Detection: Automatically detected if credential password is an OAuth2 token

Challenge-Response Authentication (CRAM-MD5)

• Secure Challenge: Server-issued challenge with hashed response
• Use Case: Legacy systems requiring CRAM-MD5
• Configuration: Standard username/password credential

SMTP TLS/SSL Support

Hydden Discovery automatically configures TLS/SSL based on the port:

• Port 587: Uses STARTTLS (upgrades connection to TLS after initial handshake)
• Port 465: Uses direct TLS/SSL connection
• Port 25: Unencrypted connection (not recommended)

SMTP Timeout

All SMTP connections have a 60-second timeout for sending email. If the mail server doesn't respond within 60 seconds, the workflow will fail and can be retried.

Common SMTP Server Configurations

Microsoft Office 365 / Exchange Online

Setting	Value
SMTP Server	smtp.office365.com
Port	587
Authentication	Username/Password or OAuth2
TLS	STARTTLS

Gmail

Setting	Value
SMTP Server	smtp.gmail.com
Port	587
Authentication	OAuth2 (recommended) or App Password
TLS	STARTTLS
Note	Enable "Less secure app access" or use App Password if not using OAuth2

Microsoft Exchange (On-Premises)

Setting	Value
SMTP Server	Your Exchange server hostname (e.g., exchange.corp.local)
Port	587 or 25
Authentication	Username/Password (domain\username or email address)
TLS	STARTTLS or none (depending on configuration)

AWS SES

Setting	Value
SMTP Server	email-smtp.[region].amazonaws.com (e.g., email-smtp.us-east-1.amazonaws.com)
Port	587 or 465
Authentication	SMTP credentials (not AWS IAM credentials)
TLS	STARTTLS or TLS/SSL

Managing Providers

Editing Providers

To modify an existing provider:

1. Navigate to Configuration > Automate.
2. On the Providers tab, find the provider in the table.
3. Click the Edit action in the provider row.
4. Update the desired fields.
5. Click Update to save changes.

Deleting Providers

To remove a provider:

1. Navigate to Configuration > Automate.
2. On the Providers tab, find the provider in the table.
3. Click the Delete action in the provider row.
4. Confirm deletion.

WARNING

Deleting a provider that is referenced by active workflows will cause those workflows to fail. Update or delete dependent workflows before removing providers.

Testing Providers

The best way to test an email provider is to create a test workflow:

1. Create a workflow using the provider (see Workflows)
2. Select a trigger that can be manually tested (e.g., Collection Succeeded)
3. Configure a simple email with a test recipient
4. Enable the workflow
5. Trigger the event (e.g., run a collection)
6. Verify the email is received

Using Email Providers in Workflows

Once configured, email providers can be used in workflows for notifications. See Workflows for complete workflow configuration instructions.

When creating a workflow with an email provider, you'll configure:

• To: Recipient email address (comma-separated for multiple recipients)
• Subject: Email subject line (supports variable substitution)
• Body: Email body content (supports variable substitution, plain text format)

Example workflow configuration:

Name: Collection Failure Alert
Trigger: Collection Failed
Action: Corporate Exchange Server (SMTP provider)
To: ops-team@example.com, security@example.com
Subject: Collection Failed: {JobName} on {Platform}
Body:
The data collection job "{JobName}" failed on {Platform}.

Error: {JobError}
Job ID: {JobID}
Site: {Site}
Last Successful Run: {LastRun}

Please investigate and retry the collection.

Troubleshooting

Issue	Solution
Email not sending	Verify SMTP server hostname and port are correct, check network connectivity to mail server, confirm credentials are valid
Authentication failure	Verify username and password are correct, check if OAuth2 token has expired, confirm sender address is authorized
TLS/SSL errors	Verify correct port for TLS configuration (587 for STARTTLS, 465 for TLS/SSL), check if mail server certificate is valid
Timeout errors	Increase timeout if mail server is slow (current limit: 60 seconds), check network latency to mail server
SendGrid API errors	Verify API key is valid and has "Mail Send" permission, check sender address is verified in SendGrid, confirm rate limits not exceeded
Sender address rejected	Verify sender address is authorized in mail system, check SPF/DKIM records if using custom domain
Emails not received	Check recipient spam/junk folders, verify recipient address is valid, review mail server logs for delivery issues

Related Topics

• Overview - Automation architecture and concepts
• Workflows - Creating and managing workflows
• Triggers - Available trigger types and variables
• ServiceNow Ticket Actions - ServiceNow provider configuration
• Using Webhooks - Webhook provider configuration
• Add to Vault - PAM provider configuration
• Credentials - Managing credentials for providers