Working with Webhooks

Webhooks allow real-time notifications of events occurring in the GEOSPAN system. They are enabled on a per-account basis and can be configured to send notifications for various events related to orders and jobs.

Note

Webhooks need to be enabled by a GEOSPAN admin. Please contact your GEOSPAN sales representative to have them enabled.

GEOSPAN Webhooks Workflow

The following workflow shows how to enable webhooks. Work with your GEOSPAN sales rep on this early release of webhooks.

Note

Webhook events are configured and triggered on an account-wide basis, rather than a per-user basis. When a webhook is set up, it listens for and returns events for all users associated with that account, not just the user who configured the webhook.

This allows for centralized event handling across your entire organization’s GEOSPAN activities, as the webhook returns events for all users under the account, regardless of which user originally set up the webhook.

  1. Enable Webhooks with your GEOSPAN sales rep:
  • Contact your GEOSPAN sales rep to enable webhooks.
  • Provide your callback URL, desired events (e.g., orderCreated, jobCompleted), and optional custom header for security.
  1. Prepare Your Server:
  • Set up an endpoint to receive POST requests at the callback URL.
  • Implement logic to handle and process webhook payloads.
  1. Secure Your Endpoint:
  • Validate the custom header if provided.
  • Implement error handling and logging.
  1. Process Webhook Events:
  • Parse JSON payloads.
  • Handle each event type (e.g., orderCreated, jobCompleted) with specific logic.
  1. Test and Monitor:
  • Work with GEOSPAN to test the integration.
  • Set up monitoring and error alerts.
  1. Scale and Optimize:
  • Ensure handling can scale with event volume.
  • Implement retry logic or queueing if needed.
  1. Maintain and Update:
  • Stay in touch with GEOSPAN for updates.
  • Adjust handling for new event types as needed.

Available Events

orderCreated

Triggered each time an order is created on the account.

Example event:

{
    "eventType": "orderCreated",
    "target": {
        "order": 100999,
        "jobs": [
            123,
            456,
        ]
    }
}

orderCompleted

Triggered each time an order is completed for the account.

Example event:

{
    "eventType": "orderCompleted",
    "target": {
        "order": 100999,
        "jobs": [
            123,
            456,
        ]
    }
}

orderCanceled

Triggered each time an order is canceled on the account. This means that all jobs on the order have been canceled as well.

Example event:

{
    "eventType": "orderCanceled",
    "target": {
        "order": 100999,
        "jobs": [
            123,
            456,
        ]
    }
}

jobCompleted

Triggered when an individual job on an order has been completed.

Example event:

{
    "eventType": "jobCompleted",
    "target": {
        "order": 100999,
        "jobs": [
            123
        ]
    }
}

jobCanceled

Triggered when an individual job on an order has been completed.

Example event:

{
    "eventType": "jobCanceled",
    "target": {
        "order": 100999,
        "jobs": [
            123
        ]
    }
}

exportReady

Triggered when a file type (e.g., dxf, xml ) for an order has finished exporting.

Example event:

{
    "eventType": "exportReady",
    "target": {
        "order": 100999,
        "jobs": [
            123
        ]
    }
}