Webhooks

Paminga has extensive support for webhooks, enabling you to connect events in Paminga to your internal systems.;

What is a Webhook?

A webhook is a notification that Paminga can send when an event occurs. But rather than notifying people (as you might do with an email or text message), a webhook is a notification that’s sent to your systems.

Let’s say an event happens that you want your systems to be notified about a prospect submits one of your forms. Paminga can send a webhook to your systems. The webhook would, in this case, include the ID and name of the form that was submitted, the ID of the Paminga contact, and the values entered by the prospect when submitting that form.

Using webhooks requires some technical expertise. Someone on your team writes a bit of code that “listens” for any incoming webhooks. When a webhook is received by that code, it can “tell” your systems that, in the example above, Prospect A just submitted Form B with “these values” typed into the form.

Which Parts of the Paminga Platform Support Webhooks?

• Forms – Trigger a webhook whenever your form is submitted

• Nurture Campaigns – Campaign webhooks notify you when a contact qualifies for a branch in your campaign (these webhooks are sent in batches. If you have 10,000 contacts qualify for a branch, you don’t want to receive 10,000 webhooks! We’ll batch these into a few webhooks that each contain an array of contact IDs).

• Alerts – Receive a webhook whenever a prospect’s activity on your website triggers a Paminga alert.;

Examples of Paminga Webhook Structure

All Paminga Webhooks contaitn a "paylod" in JSON format. Here are the formats you can expect:;

Form Webhook Example

{
	"contact_id": "749746728",
	"form_id": "1c051a75-f78c-4961-b8d5-b233229ae125",
	"form_completion_id": "4453534",
	"referrer": "",
	"ip": "73.158.92.120",
	"submission_time": "2020-12-04T20:58:01+00:00",
	"submission_values": {
		"first_name": ["Daniel"],
		"last_name": ["Golden"],
		"email_address": ["dgolden@mid-corp.com"],
		"company_name": ["MidSize Corp"]
	},
	"landing_page_url": ""
}

Campaign Webhook Example

{
	"CampaignActionQualification": [{
		"Campaign": [{
			"campaign_id": 12345,
			"campaign_name": "Your Amazing Lead Gen Campaign",
			"campaign_description": "Quite the description you've authored there...",
			"campaign_status_type": "Launched",
			"campaign_hold_status_type": "Active",
			"campaign_configuration": "Nurturing",
			"campaign_configuration_id": 1,
			"campaign_duration": "Perpetual",
			"campaign_type": "Perpetual",
			"campaign_type_id": 2,
			"campaign_launch_date": "2019-07-05T16:30:00+00:00",
			"campaign_retirement_date": null,
			"campaign_modify_date": "2019-01-15T16:28:02+00:00",
			"product_id": 12345,
			"campaign_frequency": 0,
			"folder_campaign_id": 1234,
			"rbac_role_id": null,
			"archived": false,
			"CampaignAction": [{
				"campaign_action_id": "123456",
				"campaign_action_name": "Campaign Start",
				"Contacts": {"2019-08-02T15:45:22+00:00": [1234567, 12345678, 123456789]}
			}]
		}]
	}]
}

Sample Code for Receiving Paminga Webhooks

In PHP, accessing the JSON payload is normally accomplished with the following lines of code:;

$strJson = file_get_contents('php://input'); //retrieve the JSON string
$objJson = json_decode($strJson); //convert the JSON string to a PHP object

//Sometimes we've seen it done like so...
$strJson = json_encode($_POST, true);

Webhook Best Practices

Paminga recommends that rather than processing incoming webhooks upon receipt, you store them in a queue and leverage a function to process the items in that queue.

An event queue creates a “paper trail” of the webhooks you receive and the outcomes that result from processing. You’ll thank us later! 😉