Skip to main content
The External API Request tool allows Neo Agent to call external APIs, webhooks, or internal services as part of ticket processing.

​
What It Does

When enabled, the agent can:
  • Make GET or POST requests to configured API endpoints
  • Authenticate using Bearer tokens, Basic Auth, API keys, or OAuth 2.0
  • Add custom headers for API versioning or additional metadata
  • Construct request bodies based on ticket context
  • Process and act on API responses
This tool is ideal for integrating with systems Neo doesn’t natively support.

​
How to Use

1

Add an API Configuration

Click “Add API Configuration” and provide:
  • API Name: A unique identifier (e.g., slack_alert, internal_ticketing)
  • Endpoint URL: The full URL to call
  • HTTP Method: GET or POST
2

Configure Authentication

Choose how the API authenticates requests:
MethodWhen to Use
NonePublic endpoints or pre-authenticated URLs (webhooks)
Bearer TokenAPIs that accept a static token in the Authorization header
Basic AuthAPIs requiring username/password authentication
API Key HeaderAPIs that expect an API key in a custom header (e.g., x-api-key)
OAuth 2.0 Client CredentialsAPIs requiring OAuth 2.0 token-based auth with automatic refresh
All credentials are stored securely in Azure Key Vault and never exposed in logs or event history.
3

Define Request Body Fields (POST only)

For POST requests, define the fields the agent should populate:
  • Name: The JSON key name
  • Type: String, Number, or Boolean
  • Description: Explains what the field represents (helps the agent populate it correctly)
  • Required: Whether the field must be included
4

Add Custom Instructions

Guide the agent on when and how to use each API. Include:
  • Conditions for calling the API
  • How to map ticket data to request fields
  • What to do with the response

​
Authentication Methods Explained

​
API Key Header

Use this method when the API expects an API key in a custom header rather than the standard Authorization header. Configuration:
  • Header Name: The header to use (e.g., x-api-key, api-key, X-API-KEY)
  • API Key: Your API key value
Common APIs using this method: Stripe, SendGrid, Twilio, many REST APIs.

​
OAuth 2.0 Client Credentials

Use this method for enterprise APIs that require OAuth 2.0 authentication. Neo automatically fetches and caches access tokens, refreshing them before they expire. Configuration:
  • Token Endpoint URL: The OAuth2 token endpoint (e.g., https://auth.example.com/oauth/token)
  • Token Request Parameters: Key-value pairs sent in the token request:
    • grant_type: Usually client_credentials
    • client_id: Your application’s client ID
    • client_secret: Your application’s client secret (mark as secret)
    • scope: Required scopes (if applicable)
  • Token Auth (Optional): Some providers require Basic Auth on the token endpoint
Mark sensitive values like client_secret as secrets—they’ll be stored in Azure Key Vault and masked in the UI.

​
Custom Headers

Add static headers to every request beyond authentication. Useful for:
  • API versioning: Api-Version: 2024-01
  • Tenant identification: X-Tenant-Id: acme-corp
  • Request tracing: X-Request-Source: neo-agent
Custom headers are configured per API and sent with every request to that endpoint.

​
Example: Kick-off a Rewst Workflow

Rewst user onboarding
If you have a Rewst workflow that you want Neo to decide when to kick off, you can give Neo the webhook URL. Settings:
  • API Name: rewst_user_onboarding
  • Endpoint: https://engine.rewst.io/webhooks/custom/trigger/{TRIGGER_ID}/{ORG_ID}
  • Method: POST
  • Auth: (Choose your preferred authentication method)
Request Body Fields (example):
NameTypeDescriptionRequired
user_emailStringThe email of the user to onboardYes
user_nameStringThe name of the user to onboardYes
user_phoneStringThe phone number of the user to onboardYes
microsoft_licensesStringThe Microsoft licenses to assign to the userYes

​
Example: Slack Webhook Alert

Configure an API to send alerts to a Slack channel when high-priority tickets arrive: Settings:
  • API Name: slack_high_priority_alert
  • Endpoint: https://hooks.slack.com/services/YOUR/WEBHOOK/URL
  • Method: POST
  • Auth: None (webhook URL is pre-authenticated)
Request Body Fields:
NameTypeDescriptionRequired
textStringThe message to post in SlackYes
Custom Instructions: 
When a ticket has priority "Critical" or "Emergency", use the
slack_high_priority_alert API to notify the team. Include the
ticket number, company name, and a brief summary of the issue.

​
Example: Enterprise API with OAuth 2.0

Configure an API that uses OAuth 2.0 Client Credentials for authentication: Settings:
  • API Name: crm_update_contact
  • Endpoint: https://api.example.com/v1/contacts
  • Method: POST
  • Auth: OAuth 2.0 Client Credentials
OAuth 2.0 Configuration:
  • Token Endpoint URL: https://auth.example.com/oauth/token
  • Token Request Parameters:
KeyValueSecret
grant_typeclient_credentialsNo
client_idyour-client-idNo
client_secretyour-client-secretYes
scopecontacts.writeNo
Request Body Fields:
NameTypeDescriptionRequired
emailStringContact email addressYes
nameStringContact full nameYes
notesStringAdditional notes from the ticketNo
Neo caches OAuth tokens and automatically refreshes them before expiry. You don’t need to handle token management in your instructions.

​
Best Practices

Choose names that clearly indicate purpose: jira_create_issue, pagerduty_alert, custom_crm_update. The agent uses these names to decide which API to call.
The agent relies on field descriptions to map ticket data correctly. Instead of “The message”, write “A summary of the ticket issue including the error message and affected user”.
Always enable technician approval when configuring new APIs. Review the requests the agent wants to make before allowing autonomous operation.
Add custom instructions for what the agent should do if the API returns an error—retry, escalate, or add a note to the ticket.
  • Public webhooks → None
  • Static API key in header → API Key Header
  • Static token → Bearer Token
  • Username/password → Basic Auth
  • Enterprise APIs with token refresh → OAuth 2.0 Client Credentials
Use the Test button (▶) on each API configuration to verify connectivity and authentication before enabling the workflow. This catches credential issues early.
Pin your integration to a specific API version using custom headers (e.g., Api-Version: 2024-01). This prevents breaking changes when the API provider releases updates.