Webhooks - GoBlue Documentation

What are Webhooks?

Webhooks are HTTP callbacks that allow external services to send data directly to GoBlue in real-time. When something happens in another application (like a form submission, new lead, or CRM update), that service can immediately notify GoBlue by sending data to your webhook URL. Think of webhooks as a doorbell - when someone rings it (sends data), GoBlue answers by processing that data and potentially sending a message.

How Webhooks Work in GoBlue

External Event Occurs

Something happens in your external system:

Website form is submitted
New lead is created in CRM
Customer makes a purchase
Appointment is scheduled

Data is Sent

The external service sends an HTTP POST request to your GoBlue webhook URL with relevant data.

GoBlue Processes Data

GoBlue receives the data, validates it against your form configuration, and prepares a personalized message.

Message is Queued

The message is queued for sending and will be delivered when you run the corresponding iOS Shortcut.

Webhook URL Format

Each GoBlue form has a unique webhook URL:

https://api.goblue.app/v1/forms/{form-id}/webhook

URL Components

Protocol: Always HTTPS for security
Domain: api.goblue.app - GoBlue’s API server
Path: /v1/forms/{form-id}/webhook - Specific to your form
Form ID: UUID that uniquely identifies your form

You can find your webhook URL in the GoBlue app by opening your form and tapping “Copy Capture URL”.

Required Request Format

HTTP Method

All webhook requests must use the POST method.

Headers

Include these headers in your webhook requests:

Content-Type: application/json

Request Body

Send data as JSON in the request body:

{
  "phoneNumber": "+1234567890",
  "firstName": "John",
  "lastName": "Doe",
  "email": "[email protected]",
  "serviceType": "Web Development",
  "message": "Interested in website redesign"
}

Data Requirements

Required Fields

phoneNumber

Required: Yes
Format: Any standard phone number format
Examples: +1234567890, (123) 456-7890, 123-456-7890

Optional Fields

The following fields are commonly used but optional:

firstName

Used for personalizing messages with {{firstName}} variables.Type: String
Example: “John”

lastName

Used for personalizing messages with {{lastName}} variables.Type: String
Example: “Doe”

Custom Fields

Any additional fields you’ve configured in your form:

{
  "email": "[email protected]",
  "companyName": "Acme Corp",
  "serviceType": "Consulting",
  "budget": "$5,000-$10,000",
  "timeline": "2-4 weeks",
  "source": "Google Ads"
}

Webhook Security

HTTPS Only

GoBlue webhook URLs use HTTPS encryption to protect data in transit.

Form ID Authentication

The form ID in the URL acts as an authentication token - only requests to the correct URL will be processed.

Data Validation

GoBlue validates incoming data structure and rejects malformed requests.

Rate Limiting

Webhook endpoints are rate-limited to prevent abuse:

100 requests per minute per form
429 status code returned if limit exceeded

Common Integration Patterns

Website Contact Forms

HTML Form Example:

<form action="https://api.goblue.app/v1/forms/{your-form-id}/webhook" method="POST">
  <input name="firstName" placeholder="First Name" required>
  <input name="lastName" placeholder="Last Name" required>  
  <input name="phoneNumber" placeholder="Phone" required>
  <input name="email" placeholder="Email">
  <button type="submit">Submit</button>
</form>

JavaScript/AJAX Example:

async function submitToGoBlue(formData) {
  try {
    const response = await fetch('https://api.goblue.app/v1/forms/{your-form-id}/webhook', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify(formData)
    });
    
    if (response.ok) {
      console.log('Message queued successfully!');
    }
  } catch (error) {
    console.error('Error sending data:', error);
  }
}

CRM Integration

Salesforce Example:

// Apex trigger to send data to GoBlue
Http http = new Http();
HttpRequest request = new HttpRequest();
request.setEndpoint('https://api.goblue.app/v1/forms/{form-id}/webhook');
request.setMethod('POST');
request.setHeader('Content-Type', 'application/json');

Map<String, Object> data = new Map<String, Object>();
data.put('firstName', lead.FirstName);
data.put('lastName', lead.LastName);
data.put('phoneNumber', lead.Phone);
data.put('email', lead.Email);
data.put('leadSource', lead.LeadSource);

request.setBody(JSON.serialize(data));
HttpResponse response = http.send(request);

Zapier Integration

Zapier automatically formats webhook requests correctly. Simply:

Set the webhook URL as your Zapier action endpoint
Map your trigger fields to GoBlue fields
Zapier handles the JSON formatting and HTTP request

Zapier Integration Guide

Detailed setup instructions for Zapier workflows

Testing Webhooks

Using cURL

Test your webhook endpoint with cURL:

curl -X POST https://api.goblue.app/v1/forms/{your-form-id}/webhook \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Test",
    "lastName": "User", 
    "phoneNumber": "+1234567890",
    "message": "This is a test message"
  }'

Using Postman

Create a new POST request
Set URL to your webhook endpoint
Add Content-Type: application/json header
Add JSON test data in the body
Send the request

Expected Response

Successful webhook requests return:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "success",
  "message": "Message queued successfully"
}

Error Handling

Common Error Responses

400 Bad Request

Cause: Invalid JSON format or missing required fieldsResponse:

{
  "status": "error",
  "message": "Missing required field: phoneNumber"
}

404 Not Found

Cause: Invalid form ID in the webhook URLResponse:

{
  "status": "error", 
  "message": "Form not found"
}

429 Too Many Requests

Cause: Rate limit exceeded (>100 requests/minute)Response:

{
  "status": "error",
  "message": "Rate limit exceeded. Please try again later."
}

503 Service Unavailable

Cause: Form has capturing disabledResponse:

{
  "status": "error",
  "message": "Form capturing is currently disabled"
}

Retry Logic

Implement retry logic in your webhook sending code:

async function sendWithRetry(url, data, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await fetch(url, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(data)
      });
      
      if (response.ok) return response;
      
      if (response.status === 429) {
        // Rate limited - wait before retry
        await new Promise(resolve => setTimeout(resolve, 60000));
      }
    } catch (error) {
      if (i === maxRetries - 1) throw error;
      await new Promise(resolve => setTimeout(resolve, 1000 * (i + 1)));
    }
  }
}

Monitoring Webhooks

View Incoming Data

Check the GoBlue app to monitor webhook activity:

Open the Contacts tab to see new submissions
Check the Messages tab to see queued messages
Review form settings to ensure capturing is enabled

Logging Best Practices

In your external systems, log webhook attempts:

console.log('Sending webhook to GoBlue:', {
  url: webhookUrl,
  data: formData,
  timestamp: new Date().toISOString()
});

Troubleshooting

Webhook Not Receiving Data

Verify URL

Double-check that you’re using the correct webhook URL with the right form ID.

Check Form Status

Ensure “Enable capturing” is turned on in your form settings.

Validate JSON

Use a JSON validator to ensure your payload is properly formatted.

Test with cURL

Use the cURL example above to test the endpoint directly.

Messages Not Generated

Check Required Fields

Verify that your webhook data includes a valid phoneNumber field.

Review Form Configuration

Ensure your form has a message template configured.

Verify Auto Follow-up

Check that “Auto Follow-up” is enabled in your form settings.

Best Practices

Use HTTPS

Always use secure HTTPS URLs for webhook endpoints

Validate Data

Validate data in your source system before sending

Handle Errors

Implement proper error handling and retry logic

Monitor Usage

Track webhook success rates and response times

Next Steps

Zapier Integration

Connect hundreds of apps to GoBlue with Zapier

API Reference

Complete webhook API documentation

Get Started

Core Concepts

Guides

Advanced

API Reference

​What are Webhooks?

​How Webhooks Work in GoBlue

​Webhook URL Format

​URL Components

​Required Request Format

​HTTP Method

​Headers

​Request Body

​Data Requirements

​Required Fields

phoneNumber

​Optional Fields

​Webhook Security

​HTTPS Only

​Form ID Authentication

​Data Validation

​Rate Limiting

​Common Integration Patterns

​Website Contact Forms

​CRM Integration

​Zapier Integration

Zapier Integration Guide

​Testing Webhooks

​Using cURL

​Using Postman

​Expected Response

​Error Handling

​Common Error Responses

​Retry Logic

​Monitoring Webhooks

​View Incoming Data

​Logging Best Practices

​Troubleshooting

​Webhook Not Receiving Data

​Messages Not Generated

​Best Practices

Use HTTPS

Validate Data

Handle Errors

Monitor Usage

​Next Steps

Zapier Integration

API Reference

What are Webhooks?

How Webhooks Work in GoBlue

Webhook URL Format

URL Components

Required Request Format

HTTP Method

Headers

Request Body

Data Requirements

Required Fields

Optional Fields

Webhook Security

HTTPS Only

Form ID Authentication

Data Validation

Rate Limiting

Common Integration Patterns

Website Contact Forms

CRM Integration

Zapier Integration

Testing Webhooks

Using cURL

Using Postman

Expected Response

Error Handling

Common Error Responses

Retry Logic

Monitoring Webhooks

View Incoming Data

Logging Best Practices

Troubleshooting

Webhook Not Receiving Data

Messages Not Generated

Best Practices

Next Steps