Webhooks

Webhooks let you build custom integrations on top of Partner.io. Instead of polling our API for changes, you register an HTTPS endpoint and we send it a real-time POST request whenever something you care about happens — a new lead comes in, a partner updates their details, a contact changes, and more.

This guide covers how to subscribe to events, what we send, how to verify that a request genuinely came from us, and how to build a reliable receiver.

Base URL. All management endpoints below are relative to your API base URL, for example https://api.partner.io/v1. Replace the host with the one issued to your account.

How it works

1. You create a subscription — an endpoint URL plus the list of events you want to receive.

2. An event happens in your Partner.io account (for example, a new lead is created).

3. We send an HTTP POST to your endpoint with a JSON payload describing what happened.

4. Your endpoint responds with a 2xx status code to acknowledge receipt.

You can create multiple subscriptions — for example, one endpoint for lead events and another for partner events — and each subscription can listen to any combination of events.

Authentication

The webhook management endpoints (listed below) are part of the Partner.io API and use the same authentication as the rest of the API: a bearer token sent in the Authorization header.

Authorization: Bearer YOUR_API_TOKEN

The webhook deliveries we send to your endpoint are authenticated in the opposite direction — see Verifying deliveries.

Managing subscriptions

A subscription has the following attributes:

List your subscriptions

GET /v1/webhooks

Returns a paginated list (10 per page by default; override with ?per_page=).

Create a subscription

POST /v1/webhooks
Content-Type: application/json

{
  "name": "Lead pipeline sync",
  "url": "https://example.com/hooks/partner-io",
  "secret": "whsec_a8f5f167f44f4964e6c998dee827110c",
  "is_active": true,
  "events": [10, 11]
}

Response 201 Created

{
  "data": {
    "id": 42,
    "name": "Lead pipeline sync",
    "url": "https://example.com/hooks/partner-io",
    "is_active": true,
    "events": [
      { "id": 10, "entity": "Lead", "event": "updated", "full_name": "Lead.updated" },
      { "id": 11, "entity": "Lead", "event": "deleted", "full_name": "Lead.deleted" }
    ],
    "created_at": "2026-06-26T12:34:56.000000Z",
    "updated_at": "2026-06-26T12:34:56.000000Z"
  }
}

The secret is never returned in API responses. Store it securely when you create the subscription.

Retrieve a subscription

GET /v1/webhooks/{id}

Update a subscription

PATCH /v1/webhooks/{id}

Send only the fields you want to change. Providing events replaces the subscription's event list with the IDs you send, so include the full set you want to keep.

Delete a subscription

DELETE /v1/webhooks/{id}

Response 204 No Content

Available events

Events are identified by a resource and an action. Subscribe to them by their numeric id, which you can retrieve at any time from the events endpoint:

GET /v1/webhooks/events

The events available today are:

Tip. Adding or editing a lead's contacts is also reflected as a Lead updated delivery, so subscribing to Lead.updated keeps your copy of a lead in sync as it changes over its lifetime.

Event identifiers

For historical reasons, two resources use a different internal identifier in the GET /v1/webhooks/events catalog and in the entity field of a subscription record. Use this table to map them when selecting IDs:

Because you subscribe by numeric id, you don't need to type these identifiers by hand — fetch the catalog, find the resource and action you want, and use its id.

The delivery request

When an event fires, we send an HTTP POST to your subscription's url.

Headers

Envelope

Every delivery shares the same top-level envelope:

{
  "timestamp": "2026-06-26T12:34:56.000000Z",
  "entity": "Lead",
  "event": "updated",
  "data": { }
}

Verifying deliveries

If you set a secret on a subscription, every delivery includes an X-Signature header so you can confirm it genuinely came from Partner.io and was not modified in transit.

The signature is an HMAC-SHA256 of the raw request body, keyed with your secret, and prefixed with sha256=:

X-Signature: sha256=2f1d... (64 hex characters)

To verify, compute the same HMAC over the raw body you received and compare it to the header using a constant-time comparison. Always hash the raw bytes of the request body — do not re-serialize the parsed JSON, as differences in key order or spacing will produce a different signature.

Node.js (Express)

const crypto = require('crypto');

// Capture the raw body so it can be hashed exactly as received.
app.use('/hooks/partner-io', express.raw({ type: 'application/json' }));

app.post('/hooks/partner-io', (req, res) => {
  const signature = req.get('X-Signature') || '';
  const expected =
    'sha256=' +
    crypto.createHmac('sha256', process.env.PARTNER_IO_WEBHOOK_SECRET)
          .update(req.body) // req.body is a Buffer (the raw bytes)
          .digest('hex');

  const ok =
    signature.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));

  if (!ok) return res.status(401).send('Invalid signature');

  const payload = JSON.parse(req.body.toString('utf8'));
  // ... handle the event ...

  res.sendStatus(200);
});

PHP

$raw       = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_SIGNATURE'] ?? '';
$expected  = 'sha256=' . hash_hmac('sha256', $raw, $yourWebhookSecret);

if (! hash_equals($expected, $signature)) {
    http_response_code(401);
    exit('Invalid signature');
}

$payload = json_decode($raw, true);
// ... handle the event ...

http_response_code(200);

Payload reference

The data object inside the envelope depends on the entity. All timestamps are ISO 8601 (UTC).

Lead

{
  "timestamp": "2026-06-26T12:34:56.000000Z",
  "entity": "Lead",
  "event": "updated",
  "data": {
    "id": 90817,
    "company_id": 312,
    "partner_rep_id": 4521,
    "name": "Globex Corporation",
    "data": { "industry": "Manufacturing", "employees": "500-1000" },
    "status": "approved",
    "pipeline_id": "pipe_2",
    "stage_id": "stage_negotiation",
    "deal_value": "48000.00",
    "closed_at": null,
    "deal_currency": "USD",
    "expected_close_date": "2026-08-15T00:00:00.000000Z",
    "source": "partner",
    "myshopify_domain": null,
    "partner_link_id": 77,
    "shopify_app_link_id": null,
    "event_id": null,
    "created_at": "2026-05-02T09:12:00.000000Z",
    "updated_at": "2026-06-26T12:34:56.000000Z",
    "customer_id": "cus_Qh12abcD",
    "stat_total_revenue": 48000,
    "stat_total_commission": 4800,
    "stat_total_commission_pending": 1200,
    "stat_currency": "USD",
    "contacts": [
      {
        "id": 5567,
        "name": "Dana Whitfield",
        "fields": [
          { "type": "email", "label": "Work email", "value": "[email protected]" },
          { "type": "phone", "label": "Mobile", "value": "+1 415 555 0132" }
        ]
      }
    ],
    "attribute_options": [
      {
        "id": 14,
        "group_name": "Region",
        "attribute_name": "Territory",
        "attribute_value": "North America"
      }
    ]
  }
}

Lead Contact

{
  "timestamp": "2026-06-26T12:34:56.000000Z",
  "entity": "Lead Contact",
  "event": "created",
  "data": {
    "id": 5567,
    "name": "Dana Whitfield",
    "fields": [
      { "type": "email", "label": "Work email", "value": "[email protected]" },
      { "type": "phone", "label": "Mobile", "value": "+1 415 555 0132" }
    ]
  }
}

Each entry in fields has a type (such as email or phone), a label, and a value.

Partner

{
  "timestamp": "2026-06-26T12:34:56.000000Z",
  "entity": "Partner",
  "event": "updated",
  "data": {
    "id": 88,
    "name": "Acme Digital",
    "email": "[email protected]",
    "phone": "+1 628 555 0143",
    "address": "500 Howard St",
    "city": "San Francisco",
    "state": "CA",
    "code": "94105",
    "country_code": "US",
    "website": "https://acmedigital.com",
    "logo_url": "https://cdn.partner.io/logos/acme.png",
    "profile_url": "https://app.partner.io/partners/acme-digital",
    "created_at": "2025-11-01T08:00:00.000000Z",
    "updated_at": "2026-06-26T12:34:56.000000Z"
  }
}

Partner Rep

{
  "timestamp": "2026-06-26T12:34:56.000000Z",
  "entity": "Partner Rep",
  "event": "created",
  "data": {
    "id": 4521,
    "name": "Jane Cooper",
    "email": "[email protected]",
    "phone": "+1 415 555 0188",
    "partner_id": 88,
    "status": "active",
    "created_at": "2026-06-26T12:34:56.000000Z",
    "updated_at": "2026-06-26T12:34:56.000000Z"
  }
}

Event Attendee

{
  "timestamp": "2026-06-26T12:34:56.000000Z",
  "entity": "Event Attendee",
  "event": "created",
  "data": {
    "id": "9f8c1e42-7b3a-4a91-9d2e-5c6f0b1a8d43",
    "first_name": "Dana",
    "last_name": "Whitfield",
    "email": "[email protected]",
    "phone": "+1 415 555 0132",
    "company_name": "Globex Corporation"
  }
}

Delivery, retries & best practices

Respond quickly with a 2xx. Your endpoint should acknowledge the delivery with any 2xx status code as soon as possible. Any other response (or a connection timeout) is treated as a failure. Do the heavy lifting — database writes, downstream API calls — asynchronously after you've responded.

Timeout. Each delivery attempt waits up to 30 seconds for a response.

Retries. A failed delivery is retried up to 3 times in total. If all attempts fail, the delivery is dropped, so design your integration to tolerate the occasional missed event (for example, by periodically reconciling against the REST API).

Expect at-least-once delivery. Because failed attempts are retried, your endpoint may occasionally receive the same event more than once. Make your handler idempotent — for example, de-duplicate on the combination of entity, data.id, and event, and ignore a delivery whose timestamp is older than the last one you processed for that resource.

Use HTTPS and a secret. Always point subscriptions at an HTTPS URL and set a secret so you can verify deliveries. Reject any request whose signature doesn't match.

Pause instead of deleting. To temporarily stop deliveries without losing the subscription, set is_active to false with a PATCH, then flip it back when you're ready.

Quick start

1. Stand up an endpoint that accepts POST requests and returns 200.

2. Find the event IDs you want with GET /v1/webhooks/events.

3. Create the subscription with POST /v1/webhooks, including a secret.

4. Verify the signature on each delivery and process the payload.

5. Go live — your endpoint now receives events in real time.