Setting Up Conditional Execution

Conditional Execution for Scheduled Campaigns

Step 1: Register a Listener

Your system needs to register a listener to receive notifications for scheduled Conditional Execution campaigns using EventTypeID=5. Refer to the RegisterEventListener API call documentation for details. This step only needs to be done once for all future scheduled conditional campaigns.

Step 2: Optimove Notifies the Listener that the Campaign is Ready to be Sent

Once the campaign uses Conditional Execution, Optimove processes the campaign and notifies the listener of your system specified for EventTypeID=5. At this point, Optimove will wait until the Clearance Required By time has arrived before actually scheduling the campaign for execution.

Important Note:

When using Conditional Execution, the Target Group of the campaign will be sent to your internal system in advance, giving your system time to review the customers and decide whether they should receive the campaign. The approval should arrive by the Clearance Required By time, which by default is 30 minutes before campaign execution (configurable upon request).

The Clearance Required By time is communicated to the listener at the time of the EventTypeID=5 notification.

The structure of the request:

{
  "EventTypeID": 5,
  "TimeStamp": "YYYY-MM-DD HH:MM:SS",
  "CampaignID": x,
  "CampaignDuration": y,
  "ClearanceRequiredBy": "YYYY-MM-DD HH:MM:SS"
}

Note: ClearanceRequiredBy is calculated by Optimove based on the campaign's selected execution channel(s).

Step 3: Internal Systems Review Which Customers Receive the Campaign

Once your listener receives a notification that the campaign is ready, your system calls GetProcessedCampaignCustomers to retrieve the list of customers included in this campaign.

Step 4: Notify Optimove Which Customers Should Receive the Campaign

Once the customers have been reviewed, your system notifies Optimove that customers should receive the campaign. This is accomplished using the UpdateCustomerPromotionStatus API call.

Step 5: Optimove Sends the Campaign to Eligible Customers

Once the campaign's specified Clearance Required By time arrives, Optimove will schedule the campaign for execution only to the approved customers.

Customers that were not approved will not receive the campaign.

Conditional Execution for Triggered Campaigns

Step 1: Register a Webhook

Register one or more webhooks to receive notifications for triggered Conditional Execution campaigns. All webhooks will receive all notifications, and Optimove will respect the first response received for each customer and campaign action within the defined timeout. This step only needs to be done once for all future triggered conditional campaigns. Refer to the CreateWebhook API call documentation for details. Additional webhook management APIs include GetWebhooks, GetWebhookById, and DeleteWebhook.

Webhook Registration API Call:

{
  "url": "string"
}

Response payload (201 Created):

{
  "url": "https://example.com/webhook",
  "id": "webhook1"
}

Step 2: Optional - Define Tenant Settings

Define the response timeout (default is 5000 milliseconds) and, optionally, a shared HMAC secret string for authorization with Optimove using the UpdateWebhookSettings API call.

Signature Verification

If you choose to configure a secret for your webhook:

Before sending the webhook to your endpoint, Optimove signs the request using the HMAC algorithm and the secret you provided. Validate the signature in the optimove-signature-content header.

Example:

const secret = 'abcdefg';
const hash = crypto.createHmac('sha256', secret)
  .update('I love cupcakes')
  .digest('hex');
console.log(hash);

Tenant Settings API Call Request:

{
  "timeout": 5000,
  "secret": "string"
}

Response payload (200 OK):

{
  "timeout": 5000,
  "secret": "string"
}

Step 3: Request Activation of Triggered Conditional Execution

Contact your Customer Success Manager (CSM) or Customer Success Engineer (CSE) to enable triggered Conditional Execution for your site. Once enabled, you can activate it per campaign action in the Campaign Builder.

Note: The above steps are required only once.

Step 4: Optimove Notifies the Webhook(s) that the User is Eligible for a Campaign

When a user completes the required trigger events and is eligible for a triggered campaign, Optimove sends a notification with full campaign and user details.

Notification Payload:

{
  "timestamp": 1234567890123,
  "conditional_execution_approval_deadline": 1234567890999,
  "request_uid": "string",
  "is_hashed": false,
  "user": {
    "user_id": "string",
    "is_visitor": false,
    "personalization": {
      "attribute_key1": "attribute_value1",
      "attribute_key2": "attribute_value2"
    }
  },
  "occurrence": {
    "date": "YYYY-MM-DD",
    "series_id": "string",
    "occurrence_id": "string",
    "target_group": {
      "id": 123,
      "name": "string"
    },
    "notes": "string",
    "tags": ["string"],
    "communication_type": "triggered",
    "action": {
      "id": 1,
      "name": "string",
      "is_control": false,
      "promotions": [
        {
          "name": "string",
          "code": "string"
        }
      ],
      "channels": [
        {
          "id": 1,
          "name": "string",
          "brand_id": "string",
          "template": {
            "id": 1,
            "name": "string"
          }
        }
      ]
    }
  },
  "trigger_context": {
    "id": 1,
    "name": "string",
    "events": [
      {
        "key": "string",
        "timestamp": 1234567890,
        "parameters": {
          "param_key1": "param_value1",
          "param_key2": "param_value2"
        }
      }
    ]
  }
}

Step 5: Internal Systems Review if the User Should Receive the Campaign

Perform the necessary internal checks or validations.

Step 6: Notify Optimove if the User Should Receive the Campaign

Send approval using the SendWebhookApproval API.

Approval Payload:

{
  "timestamp": 1234567890123,
  "request_uid": "string",
  "approved": true,
  "additional_data": {}
}

Step 7: Optimove Sends the Campaign to the User

If the user is approved before the timeout, Optimove sends the campaign. If delayed execution is configured, the delay begins at approval time.

Note: Triggered Conditional Execution is not supported for web page pop-up campaigns.