Skip to content

Webhooks

Introduction to Webhooks in Mythradon

What is a Webhook?

A webhook is a way for Mythradon to automatically notify another application when something important happens—like a new customer being added, a task being updated, or an order being deleted. Instead of requiring another application to constantly check for changes, a webhook allows Mythradon to send relevant data to a designated URL when an event happens.

In simple terms, a webhook works like this:

  • You tell Mythradon what kind of event to watch for (e.g. "when an Account is created").
  • You provide a URL from another system where the data should be sent.
  • Whenever that event happens, Mythradon sends a message (an HTTP POST request) to the specified URL, including information about the event.

This mechanism makes it easy to integrate Mythradon with other platforms, services, or in-house systems without manual intervention.

Why Use Webhooks?

Webhooks help automate and streamline workflows across your business systems by:

  • Keeping systems in sync – automatically update another system when something changes in Mythradon.
  • Triggering actions – start a process in another application when a specific event occurs (e.g. sending an SMS when a customer status changes).
  • Reducing complexity – no need for the other system to constantly "poll" Mythradon for changes.

What Events Can Webhooks Listen For?

Webhooks in Mythradon can be configured to respond to a wide range of system events, including changes on both standard and custom entities. Supported event types include:

  • Create – Triggered when a new record is added (e.g. Account.create)
  • Update – Triggered when any record field is modified (e.g. Contact.update)
  • Delete – Triggered when a record is removed (e.g. Order.delete)
  • fieldUpdate – Triggered only when a specific field is updated (e.g. Account.fieldUpdate.assignedUserId)

The fieldUpdate event type allows you to target very specific changes within records. For example:

  • Account.fieldUpdate.assignedUserId is triggered only when the assignedUserId field on an Account record is changed.

This is especially useful for integrations or automations that depend on a particular value being updated, such as assigning a user, updating a status, or setting a priority.

When a fieldUpdate event is triggered, the webhook payload will include the new value(s) of the updated field(s), along with the associated record metadata.

Custom Entities

Mythradon's Webhooks fully support custom entities.

How Are Webhooks Created?

There are two ways to create webhooks in Mythradon:

  1. Via the Application Administration Interface - Administrators can manually create and manage webhooks through the Administration → Webhooks menu.

  2. Via the API - Other applications can programmatically register webhooks using Mythradon's API. To do this, the API User must:

  • Have the Webhooks permission enabled in their Role
  • Have access to the relevant entities the webhook targets.

Subscribing to a Webhook Event

  • The act of registering a webhook for a specific event (e.g., Account.create) is often referred to as "subscribing to a webhook event."

  • The registered webhook is considered a subscription, and Mythradon acts as the publisher of those events.

Each webhook configuration must include:

  • The event it should listen to
  • The destination URL to send data to

When the event occurs, Mythradon sends a HTTP POST request to that URL with a structured JSON payload describing the change.

What Data Is Sent?

The data delivered in a webhook notification is determined by two key factors: the entity that triggered the webhook and the API User associated with it. This layered approach ensures data security and relevance by only including information the API User is permitted to access.

  • With an API User assigned: The webhook payload is filtered according to that user's access rights, ensuring compliance with their security permissions.
  • Without an API User assigned: The system defaults to including all data available for the triggered event, without filtering.

This mechanism provides flexible control over data exposure while maintaining strict access boundaries where required.

Security Best Practice

To minimise the risk of unintended data exposure, it is strongly recommended to always associate webhooks with an API User assigned to a Role with the least privileges necessary.

This ensures the webhook only has access to the specific data it needs, helping to prevent accidental data leakage and supporting the principle of least privilege in your integration design.

Creating a Webhook

Webhooks in Mythradon can be created either through the administration interface or programmatically via the API. Both methods allow you to subscribe to system events and define how and where event data should be delivered.

Option 1: Create a Webhook via the Administration Interface

To create a webhook through the admin UI:

  1. Navigate to Administration → Webhooks from the Menu Button.
  2. Click Create Webhook.
  3. Fill in the required fields:
  • Event
  • URL
  • API User
  1. Click Save to activate the webhook.
Create Webhook - Light Create Webhook - Dark

Custom Field Event Subscriptions

The Event field offers a dropdown of standard system events but can be edited to monitor updates to specific fields.

Example: To subscribe to changes on a custom field scoreCust within the Account entity:

Account.fieldUpdate.scoreCust

Use the Entity Manager to obtain the correct entity and field names.

⚠️ Field names are case-sensitive. Ensure the field exists—otherwise, the webhook cannot be saved.

Webhook Properties

When creating a webhook (via UI or API), configure the following properties:

Property Description
Event The system event that triggers the webhook (e.g. Contact.update, Order.delete, or Account.fieldUpdate.status).
Is Active Controls whether the webhook is active. New webhooks are active by default.
URL The destination endpoint that receives the webhook payload. Must accept HTTPS POST requests with JSON bodies.
API User Determines the scope of data sent in the payload, based on the API User's role and permissions. Learn more.

Option 2: Subscribe to Webhooks via the API

You can also register and manage webhooks programmatically using Mythradon's REST API.

Step 1: Create a Role for Webhooks

  • Navigate to Administration → Roles from the Menu Button.
  • Click Create Role.

  • Ensure the role has:

  • Webhooks enabled.

  • Read access to the entity being monitored (e.g. Contact).

  • Click Save.

API User Web Hook Role - Light API User Web Hook Role - Dark

Step 2: Create an API User

  • Navigate to Administration → API Users from the Menu Button.
  • Click Create API User.
  • Assign the Role created in Step 1.
  • Click Save to generate the API Key.
API User Web Hook Role - Light API User Web Hook Role - Dark

Authentication Required

The API Key is required to authenticate your API requests when registering webhooks.

Step 3: Register a Webhook via API

You can register a webhook using a simple HTTP POST request. The example below demonstrates how to subscribe to the Contact.create event using curl.

Note

The url in this example points to a temporary endpoint generated by Webhook Tester, which is commonly used to simulate receiving systems during testing.

CURL Example
curl -X POST https://<your-app-url>/api/v1/Webhook \
  -H 'X-Api-Key: <your-api-key>' \
  -H 'Content-Type: application/json' \
  -d '{
        "event": "Contact.create",
        "url": "https://webhook-test.com/2a2ae8c727d025d5acf7648dca8e0642"
      }'

API Authentication

Webhook registration requires authentication using an API key. Pass the API User’s API key in the request header as:

X-Api-Key: YOUR_API_USER_API_KEY

This request tells the system to notify your specified endpoint whenever a new Contact record is created.

If the webhook registration request is successful, the API will return a JSON response similar to the following:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
{
    "id": "6858b5ae40ce99e1d",
    "deleted": false,
    "event": "Contact.create",
    "url": "https:\/\/webhook-test.com\/2a2ae8c727d025d5acf7648dca8e0642",
    "isActive": true,
    "entityType": "Contact",
    "type": "create",
    "field": null,
    "secretKey": "89741d8aa6ddda0336574226e59c2433",
    "createdAt": "2025-06-23 02:02:22",
    "modifiedAt": "2025-06-23 02:02:22",
    "createdById": "68552cd4d18b6e397"
}

Key Fields in the Webhook Registration Response

Field Description
id A unique identifier assigned to the created webhook.
event The event the webhook is subscribed to (e.g., Contact.create).
entityType The type of entity associated with the event (e.g., Contact).
type The type of change being monitored (e.g., create, update, or delete).
field If specified, indicates the exact field being watched for changes.
url The endpoint that will receive the webhook notification when triggered.
isActive Indicates whether the webhook is currently active and processing events.
deleted Shows whether the webhook has been marked as deleted.
secretKey A secure, shared key used to verify that incoming webhook requests are authentic. Useful for validating request signatures.
createdAt The timestamp when the webhook was created.
modifiedAt The timestamp of the last modification to the webhook.
createdById The unique ID of the user or system that created the webhook.

SecretKey

The secretKey is a critical value used to verify that incoming webhook requests originate from Mythradon. Your receiving system should use this key to validate the authenticity of webhook notifications—typically by checking the signature included in each request header.

⚠️ Important: You can access the secretKey at any time by viewing the webhook definition within Mythradon. Be sure to keep it secure and do not expose it publicly.

API Endpoint to Register Webhook

POST <your-app-url>/api/v1/Webhook

Request Body:

{
  "event": "Account.update",
  "url": "https://your-system.com/webhooks/receive"
}

Successful Response:

{
  "id": "abc123456",
  "secretKey": "randomlyGeneratedSecretKey"
}

Deleting a Webhook via API

To unsubscribe or remove a webhook:

Endpoint:

DELETE api/v1/Webhook/{WEBHOOK_ID}

Replace {WEBHOOK_ID} with the unique ID of the webhook you wish to delete.

Webhook Payload Format

Webhooks in Mythradon send HTTP POST requests with the Content-Type: application/json. Payloads are always delivered as a JSON array—even when only a single event is included.

Sample Payloads

Single event:

[
  {
    "id": "someId",
    "name": "some name"
  }
]

Multiple events:

[
  {
    "id": "someId1",
    "name": "some name 1"
  },
  {
    "id": "someId2",
    "name": "some name 2"
  }
]

Payloads are grouped and delivered in batches by the scheduled job Process Webhook Queue, which runs every 5 minutes by default. To adjust the execution frequency, please contact Mythradon support.

Webhook Error Handling

When Mythradon attempts to send a webhook request and encounters an error, it responds based on the type of failure encountered:

Retriable Errors

For the following error responses or connection issues, Mythradon will automatically retry delivery:

  • 400 – Bad Request
  • 401 – Unauthorised
  • 403 – Forbidden
  • 404 – Not Found
  • 405 – Method Not Allowed
  • 408 – Request Timeout
  • Connection timeout or Connection failure

These retries are managed by the scheduled job Process Webhook Queue, which continues retrying based on a backoff strategy until the request is successfully delivered or the retry limit is reached.

Permanent Errors

  • 410 – Gone If the target endpoint returns a 410 Gone status, the webhook is assumed to be permanently invalid and will be automatically removed from the system. No further delivery attempts will be made.

Validating Webhook Requests with X-Signature

To verify that incoming webhook requests are authentic and untampered, Mythradon supports HMAC-based signature validation. Each webhook request includes an x-signature HTTP header that you can use to confirm the request was sent by Mythradon and not forged by a third party.

How Signature Checking Works

When a webhook is triggered, Mythradon signs the outgoing request body using HMAC-SHA256 and the webhook's secretKey (generated when the webhook was created). The resulting signature is sent in the x-signature header.

Your receiving endpoint can recompute the HMAC signature using the same secretKey and compare it against the x-signature header.

Signature checking

It's possible to check the authenticity of a webhook request to ensure it is being sent via your Mythradon system by comparing the signature passed in the Signature header with a value calculated on the server that receives the request.

Invalid Signature

If the signature validation fails, do not process the request. Treat the request as untrusted and discard it immediately to prevent potential security risks or unauthorised access.

PHP Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
<?php
// Configuration
$webhookId = 'YOUR WEBHOOK ID'; // Replace with your actual webhook ID
$secretKey = 'YOUR WEBHOOK SECRET KEY'; // Replace with your actual secret key

// Setup log file - Ensure you have write permissions to the tmp folder
$logFile = sys_get_temp_dir() . '/webhook_received_' . date('Ymd_His') . '.log';

// Get raw POST body
$rawBody = file_get_contents('php://input');

// Get headers
$headerSignatureKey = 'X-Signature';
$headers = getallheaders();
$signatureHeader = $headers[$headerSignatureKey] ?? null;

// Generate expected signature

// Assuming your signature is base64-encoded HMAC-SHA256 of the body using the secretKey
$expectedHash = base64_encode($webhookId . ':' . hash_hmac('sha256', $rawBody, $secretKey, true));

// Compare signature
$signatureValid = hash_equals($expectedHash, $signatureHeader);
$signatureStatus = $signatureValid ? 'VALID' : 'INVALID';

// Build header log
$headerLog = "Received Headers:\n";
foreach ($headers as $key => $value) {
    $headerLog .= "$key: $value\n";
}

// Get current date/time for log
$receivedAt = date('Y-m-d H:i:s');

// Compose full log content
$logContent = <<<LOG
=== Webhook Received at: $receivedAt ===

$headerLog

--- Raw Body ---
$rawBody

--- Signature Check ---
Provided Signature: $signatureHeader
Expected Signature: $expectedHash
Signature Status: $signatureStatus

LOG;

// Write to log file
file_put_contents($logFile, $logContent);

// Respond with 200 OK
http_response_code(200);
echo 'OK';
exit;
  • webhookId – The unique identifier for the webhook, available from either the API registration response or via Administration → Webhooks.
  • secretKey – Provided in the response when the webhook is created, or accessible via Administration → Webhooks.
  • rawBody – The full body of the incoming webhook request.

Note

  • The X-Signature is a HMAC-SHA256 hash.

  • Always use the raw request body (not the parsed JSON) for signature computation.

  • Store the secretKey securely; it is provided in the response when you register the webhook via API.

Sample Request

This is a sample of a Webhook request coming into your registered system.

POST /webhooks/receive HTTP/1.1
Content-Type: application/json
X-Signature: 8f9c230c47d3ba1a6d0ae2c7b8281ea61f8de44f70e9bbcc2baf938c8dcf4975

[
  {
    "id": "a1b2c3",
    "event": "Contact.create",
    "data": {
      "firstName": "Jane",
      "lastName": "Doe"
    }
  }
]

Webhook Configuration Parameters

The following are the default system-level configuration parameters that govern how webhooks operate in Mythradon. These settings control batching, retries, timeouts, and limits per user. If you require any changes to these defaults, please contact Mythradon support.

Parameter Default Description
Max Count Per User 50 Maximum number of active webhooks allowed per user.
Queue Event Portion Size 20 Number of events processed per run of the Process Webhook Queue job.
Queue Portion Size 20 Number of webhook requests sent in a single batch from the queue.
Batch Size 50 Maximum number of event payloads grouped together into a single webhook request.
Max Attempt Number 4 Maximum number of retry attempts for a failed webhook delivery.
Fail Attempt Period 10 minutes Interval between retry attempts when a webhook delivery fails.
Connect Timeout 5 seconds Maximum time allowed to establish a connection to the webhook endpoint.
Timeout 10 seconds Maximum total time allowed for a webhook request to complete, including both connection and response.

Debugging Webhooks

If your webhook does not appear to be working as expected, follow these steps to troubleshoot:

✅ Step 1: Verify the Scheduled Job Is Running

Ensure the Process Webhook Queue scheduled job is active. This job is responsible for sending queued webhook payloads. If it's paused or not scheduled, webhook events will not be dispatched.

Webhook Scheduled Job - Light Webhook Scheduled Job - Dark

✅ Step 2: Confirm the Webhook Is Active

Check that the specific webhook is marked as Active in its configuration. Inactive webhooks will not receive events, even if triggered.

Webhook Is Active - Light Webhook Is Active - Dark

✅ Step 3: Trigger the Event

Perform an action in Mythradon that matches the event configured in your webhook. This should queue the event for delivery.

✅ Step 4: Check the Scheduled Job Log

Open the Process Log for the Process Webhook Queue scheduled job to confirm that the job has executed and processed webhook events. Look for any error messages or status codes returned by the target endpoint.

Webhook Scheduled Job Process Log - Light Webhook Scheduled Job Process Log - Dark

By confirming each of these steps, you can quickly identify and resolve common issues affecting webhook delivery.

Testing Webhooks

You can test webhook functionality in Mythradon using a variety of tools. One simple method to view and debug outgoing webhook payloads is by using Webhook Tester, a free online webhook inspection tool.

Steps to Test

  1. Open Webhook Tester in your browser.
  2. Copy the generated URL and paste it into the URL field when creating or editing a webhook in Mythradon.
  3. Trigger an event in Mythradon that activates the webhook.
  4. Return to the Webhook Tester tab to view the payload and inspect headers, status codes, and content.
Webhook Tester Home Page

Example - Create Account Event

Create Webhook - Light Create Webhook - Dark
Webhook Tester View Payload
Sample Account Payload JSON Structure
[
    {
        "id": "6854d45f06d15a2b8",
        "name": "ACME Inc",
        "deleted": false,
        "website": "acmeinc.co",
        "emailAddress": "info@acmeinc.co",
        "phoneNumber": "+61 2 9987 0000",
        "type": "Customer",
        "industry": "Advertising",
        "contactIsInactive": false,
        "billingAddressStreet": "9 Smith St",
        "billingAddressCity": "Rozelle",
        "billingAddressState": "New South Wales",
        "billingAddressCountry": "Australia",
        "billingAddressPostalCode": "2039",
        "shippingAddressStreet": "9 Smith St",
        "shippingAddressCity": "Rozelle",
        "shippingAddressState": "New South Wales",
        "shippingAddressCountry": "Australia",
        "shippingAddressPostalCode": "2039",
        "description": "This is a test Account record used for testing a Webhook",
        "createdAt": "2025-06-20 03:24:15",
        "modifiedAt": "2025-06-20 03:24:15",
        "targetListIsOptedOut": false,
        "scoreCust": null,
        "emailAddressIsOptedOut": false,
        "emailAddressIsInvalid": false,
        "phoneNumberIsOptedOut": false,
        "phoneNumberIsInvalid": false,
        "billingAddressLatitude": -33.8639855,
        "billingAddressLongitude": 151.1785216,
        "shippingAddressLatitude": -33.8639855,
        "shippingAddressLongitude": 151.1785216,
        "emailAddressData": [
            {
                "emailAddress": "info@acmeinc.co",
                "primary": true,
                "optOut": false,
                "invalid": false,
                "lower": "info@acmeinc.co"
            }
        ],
        "phoneNumberData": [
            {
                "phoneNumber": "+61 2 9987 0000",
                "primary": true,
                "type": "Office",
                "optOut": false,
                "invalid": false
            }
        ],
        "createdById": "6822eddc679fbb330",
        "assignedUserId": "6822eddc679fbb330",
        "assignedUserName": "Brian Tanaka",
        "teamsIds": [],
        "teamsNames": {},
        "isFollowed": true
    }
]

Data Security

Do not use real or sensitive data when testing with third-party tools like Webhook Tester. Treat all data posted to such services as publicly visible and insecure. Use only anonymised or sample data for testing purposes.

Alternatives to Webhook Tester

In addition to Webhook Tester, there are several other free tools available for testing and inspecting webhook requests:

  • RequestBin – Quickly generate a temporary endpoint to capture and inspect HTTP requests in real time.
  • Beeceptor – Offers custom endpoints, detailed request logging, and rules for mocking API responses.

These tools are ideal for debugging webhook payloads and verifying headers, content types, and delivery behaviour—without the need to run a local server. Use them during development to ensure your webhooks are firing as expected.

See also