dolfin.http.get & dolfin.http.post
#
Use get to query external REST APIs and post to send webhook alerts or sync records to external platforms.
TypeScript Signatures #
typescript
dolfin.http.get<T = unknown>(
url: string,
options?: {
headers?: Record<string, string>;
timeoutMs?: number;
}
): Promise<{ status: number; body: T }>;
dolfin.http.post<T = unknown>(
url: string,
body: unknown,
options?: {
headers?: Record<string, string>;
timeoutMs?: number;
}
): Promise<{ status: number; body: T }>;
Method Details #
dolfin.http.get(url, options?)
#
Executes an outbound HTTP GET request to an external HTTPS/HTTP URL.
Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
url | string | Yes | — | Complete target URL (e.g. "https://api.github.com/users/octocat"). |
options.headers | Record<string, string> | No | {} | Custom HTTP request headers (e.g. Authorization, Accept). |
options.timeoutMs | number | No | 8000 | Request timeout in milliseconds (max 8,000 ms). |
dolfin.http.post(url, body, options?)
#
Sends a JSON-serialized POST request payload to an external webhook or endpoint.
Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
url | string | Yes | — | Target URL destination. |
body | any | Yes | — | Request payload object. Automatically serialized to JSON (Content-Type: application/json). |
options.headers | Record<string, string> | No | {} | Additional HTTP headers to attach. |
options.timeoutMs | number | No | 8000 | Request timeout in milliseconds (max 8,000 ms). |
Minimal Example: Slack Webhook #
typescript
async function run(context: Context, dolfin: DolfinApi): Promise<void> {
const { lead } = context;
const slackResponse = await dolfin.http.post(
"https://hooks.slack.com/services/T000/B000/XXXXX",
{
text: `🚀 Lead *${lead.name}* reached Stage *${lead.stageId}*!`
}
);
console.log(`Slack webhook status: ${slackResponse.status}`);
}
Production Recipe: Syncing Deal to External ERP & Recording External ID #
typescript
async function run(context: Context, dolfin: DolfinApi): Promise<void> {
const { lead } = context;
const crm = await dolfin.crm.module(lead.moduleId);
console.log(`Syncing lead ID ${lead.id} to external ERP`);
// 1. Post to external ERP endpoint
const erpPayload = {
crm_lead_id: lead.id,
customer_name: lead.name,
email: lead.email,
phone: lead.phone,
contract_estimate: Number(lead.meta?.deal_value || 0)
};
const response = await dolfin.http.post<{ erp_id: string; status: string }>(
"https://api.external-erp.com/v2/opportunities",
erpPayload,
{
headers: {
"Authorization": "Bearer SECURE_API_TOKEN",
"X-Tenant-Origin": "dolfin-crm"
},
timeoutMs: 6000
}
);
if (response.status >= 200 && response.status < 300 && response.body?.erp_id) {
// 2. Persist ERP ID in lead custom metadata
await crm.leads.update(lead.id, {
meta: {
...lead.meta,
erp_sync_id: response.body.erp_id,
erp_synced_at: new Date().toISOString()
}
});
await crm.leads.notes.add(
lead.id,
`✅ Synchronized with ERP (External ID: ${response.body.erp_id}).`
);
} else {
await crm.leads.notes.add(
lead.id,
`⚠️ ERP Sync failed with HTTP status ${response.status}.`
);
}
}
Error Handling & Guardrails #
| Scenario | Thrown Error | Resolution |
|---|---|---|
| Destination resolves to private IP | Error: Forbidden destination IP address | Verify destination URL is a publicly accessible domain. Private IPs (10.0.0.0/8, 192.168.0.0/16, 127.0.0.1) are blocked. |
| Request takes > 8 seconds | DOMException: The operation was aborted | Optimize remote endpoint response latency or catch timeout errors gracefully. |
| More than 5 HTTP requests in one run | Error: Exceeded maximum HTTP calls per execution (5) | Batch external calls or trigger subsequent workflows asynchronously. |
| Response payload > 1 MB | Error: Response size exceeds the maximum limit | Query remote endpoints with pagination filters or specific field projections. |
⚠️
Warning
Secrets like API keys should not be hardcoded in plain text when sharing scripts across team members. Ensure your endpoint headers are properly configured.