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

ParameterTypeRequiredDefaultDescription
urlstringYes—Complete target URL (e.g. "https://api.github.com/users/octocat").
options.headersRecord<string, string>No{}Custom HTTP request headers (e.g. Authorization, Accept).
options.timeoutMsnumberNo8000Request 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

ParameterTypeRequiredDefaultDescription
urlstringYes—Target URL destination.
bodyanyYes—Request payload object. Automatically serialized to JSON (Content-Type: application/json).
options.headersRecord<string, string>No{}Additional HTTP headers to attach.
options.timeoutMsnumberNo8000Request 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 #

ScenarioThrown ErrorResolution
Destination resolves to private IPError: Forbidden destination IP addressVerify 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 secondsDOMException: The operation was abortedOptimize remote endpoint response latency or catch timeout errors gracefully.
More than 5 HTTP requests in one runError: Exceeded maximum HTTP calls per execution (5)Batch external calls or trigger subsequent workflows asynchronously.
Response payload > 1 MBError: Response size exceeds the maximum limitQuery 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.