Custom Webhook TypesPro

You can create your own Webhook types and add them to Freeform.

Setup GuideRevised in 5.0+

The creation of a custom Webhook integration in Freeform will require using a custom Craft module. This guide assumes you already have that knowledge. If not, please check out the guide we have.

View the guide on how to build a custom module.

To add a custom webhook integration, you will need to create a new class which must implement the \Solspace\Freeform\Library\Integrations\Types\Webhooks\WebhookIntegrationInterface interface.

To make things easier for you, you can extend the \Solspace\Freeform\Library\Integrations\Types\Webhooks\WebhookIntegration class, which already has a URL property as well as being capable of storing and exposing various other base properties, such as id, enabled, handle, name, etc.

Then you would implement the ::trigger(Form $form) method to handle posting your webhooks.

For the sake of this example, let's assume you just want your webhook to post the form ID, name, and submission ID to an endpoint at https://my.test.com. Here is what that class would look like.

1

Create the Webhook Integration

<?php

namespace Modules\Webhooks;

use GuzzleHttp\Client;
use Solspace\Freeform\Attributes\Integration\Type;
use Solspace\Freeform\Form\Form;
use Solspace\Freeform\Library\Integrations\Types\Webhooks\WebhookIntegration;

// To be able to register this integration type, you must define
// some metadata about it. Like specifying the readme and icon paths.
// Readme uses Markdown markup.

#[Type(
    name: 'My Basic Webhook',
    type: Type::TYPE_WEBHOOKS,
    readme: __DIR__.'/README',
    iconPath: __DIR__.'/icon.svg',
)]
class BasicWebhook extends WebhookIntegration
{
    public function trigger(Form $form): void
    {
        $submission = $form->getSubmission();

        // Create the payload that we will send
        $json = [
            'form' => [
                'id' => $form->getId(),
                'name' => $form->getName(),
            ],
            'submission' => [
                'id' => $submission->id,
            ],
        ];

        // Create a new Guzzle Client instance
        $client = new Client();

        // Get the URL the user has configured in their settings
        $url = $this->getUrl();

        try {
            // Post payload to the endpoint
            $client->post($url, ['json' => $json]);
        } catch (\Exception $e) {
            $this->processException($e, self::LOG_CATEGORY);
        }
    }
}

2

Register the Webhook Integration

Now that the integration type has been created, we need to register it with Freeform to make it available when creating new integrations. We do this by listening to the \Solspace\Freeform\Services\Integrations\IntegrationsService::EVENT_REGISTER_INTEGRATION_TYPES event.

<?php

namespace Modules;

use yii\base\Module;
use yii\base\Event;
use Modules\Webhooks\BasicWebhook;
use Solspace\Freeform\Services\Integrations\IntegrationsService;
use Solspace\Freeform\Events\Integrations\RegisterIntegrationTypesEvent;

class MyModule extends Module
{
    public function init(): void
    {
        parent::init();

        Event::on(
            IntegrationsService::class,
            IntegrationsService::EVENT_REGISTER_INTEGRATION_TYPES,
            function (RegisterIntegrationTypesEvent $event) {
                $event->addType(BasicWebhook::class);
            }
        );
    }
}

3

Set up the Webhook Integration

Once this is done, you should be able to see your webhook type as an option when creating a new Freeform Webhook integration.

Finished!