Skip to main content
For platform users: See the Data Input overview to understand how connections and data processing work.

​
Overview

Webhooks are POST requests sent to your endpoint when events occur in Nectar — connections created, documents processed, and more. Your endpoint should return a 2xx response within 15 seconds to acknowledge receipt. If your framework enables CSRF protection by default, disable it for the webhook endpoint. Verify every incoming webhook using signature verification before processing.

​
Set up webhooks

1

Get your webhook portal URL

Call the configure webhook endpoint (see the API Reference tab) with your API key. The response contains a Svix portal URL valid for 7 days.
2

Add an endpoint

In the Svix portal, add your endpoint URL and select the event types you want to subscribe to. If you don’t select any event types, the endpoint receives all events by default.
If you don’t have a URL ready yet, click Use Svix Play to generate a temporary URL where you can inspect incoming events.
3

Test your endpoint

Use the Testing tab in the Svix portal to send example events to your endpoint. Click into any message to view the payload, delivery attempts, and success or failure status.

​
Event types

Nectar sends the following event types:
Event typeTrigger
connection.created.v2A new connection is created
connection.updated.v2A connection’s status or details change
connection.validated.v2A connection has been validated by Nectar
document.created.v2A new document is processed
document.updated.v2An existing document is reprocessed or updated
Browse the full list in the Svix event catalog.

​
connection.created.v2

Sent when a new connection is created. 
{
  "company": {
    "externalId": "269350a4-8595-42cc-96ee-bf047d093505",
    "id": "91c21c6b-5f3f-4d5f-9fb9-02530ef4b13c",
    "name": "Demo Company",
    "publicId": "cb78b85c-e68e-48de-a99e-e88862076823"
  },
  "created": "2024-09-06T00:15:43.073014",
  "datasource": {
    "name": "Los Angeles Department of Water and Power"
  },
  "id": "a6c70a54-34e7-4277-80b0-412869ce087c",
  "sitesRelations": [
    {
      "accountIds": ["0137746423"],
      "datasourceTypes": ["ELECTRICITY"],
      "site": {
        "id": "67e72ddf-9e9c-42b6-81da-13c1130c691a",
        "name": "California Facility 1"
      }
    }
  ],
  "status": "CONNECTED",
  "updated": "2024-09-06T00:15:43.073032",
  "url": "https://ladwp.com"
}

​
connection.updated.v2

Sent when a connection’s status or details change. Includes protectedChanges (a list of fields that changed) and old (previous values for those fields). 
{
  "eventType": "connection.updated.v2",
  "protectedChanges": ["status"],
  "old": {
    "status": "PENDING"
  },
  "company": {
    "externalId": "269350a4-8595-42cc-96ee-bf047d093505",
    "id": "91c21c6b-5f3f-4d5f-9fb9-02530ef4b13c",
    "name": "Demo Company",
    "publicId": "cb78b85c-e68e-48de-a99e-e88862076823"
  },
  "created": "2024-09-06T00:15:43.073014",
  "datasource": {
    "name": "Los Angeles Department of Water and Power"
  },
  "id": "a6c70a54-34e7-4277-80b0-412869ce087c",
  "sitesRelations": [
    {
      "accountIds": ["0137746423"],
      "datasourceTypes": ["ELECTRICITY"],
      "site": {
        "id": "67e72ddf-9e9c-42b6-81da-13c1130c691a",
        "name": "California Facility 1"
      }
    }
  ],
  "status": "CONNECTED",
  "updated": "2024-09-07T12:30:00.000000",
  "url": "https://ladwp.com"
}

​
connection.validated.v2

Sent when a connection has been validated by Nectar. The payload shape is the same as connection.created.v2.

​
document.created.v2

Sent when a new document is processed. 
{
  "eventType": "document.created.v2",
  "id": "b2d4e6f8-1234-5678-9abc-def012345678",
  "company": {
    "externalId": "269350a4-8595-42cc-96ee-bf047d093505",
    "id": "91c21c6b-5f3f-4d5f-9fb9-02530ef4b13c",
    "name": "Demo Company",
    "publicId": "cb78b85c-e68e-48de-a99e-e88862076823"
  },
  "site": {
    "id": "67e72ddf-9e9c-42b6-81da-13c1130c691a",
    "name": "California Facility 1"
  },
  "created": "2024-09-10T14:22:00.000000",
  "updated": "2024-09-10T14:22:00.000000"
}

​
document.updated.v2

Sent when an existing document is reprocessed or updated. Includes old with previous field values. 
{
  "eventType": "document.updated.v2",
  "old": {
    "updated": "2024-09-10T14:22:00.000000"
  },
  "id": "b2d4e6f8-1234-5678-9abc-def012345678",
  "company": {
    "externalId": "269350a4-8595-42cc-96ee-bf047d093505",
    "id": "91c21c6b-5f3f-4d5f-9fb9-02530ef4b13c",
    "name": "Demo Company",
    "publicId": "cb78b85c-e68e-48de-a99e-e88862076823"
  },
  "site": {
    "id": "67e72ddf-9e9c-42b6-81da-13c1130c691a",
    "name": "California Facility 1"
  },
  "created": "2024-09-10T14:22:00.000000",
  "updated": "2024-09-12T08:15:00.000000"
}

​
Signature verification

Verify webhook signatures to confirm that messages are genuinely sent by Nectar. For background on why this matters, see Why verify webhooks. Svix provides libraries that make verification straightforward: 
import { Webhook } from "svix";

const secret = "whsec_your_signing_secret";

const headers = {
"svix-id": "msg_your_message_id",
"svix-timestamp": "1614265330",
"svix-signature": "v1,your_signature_here",
};
const payload = '{"test": 2432232314}';

const wh = new Webhook(secret);
const verified = wh.verify(payload, headers);
For additional languages and details, see the Svix verification documentation.

​
Retry schedule

Svix uses exponential backoff to retry failed deliveries. Each period starts after the preceding attempt fails:
AttemptDelay
1Immediately
25 seconds
35 minutes
430 minutes
52 hours
65 hours
710 hours
810 hours
If an endpoint is removed or disabled, remaining delivery attempts are cancelled.

​
Troubleshooting

​
Not using the raw payload body

This is the most common issue. Signature verification uses the raw string body of the message payload. If you serialize the JSON with methods like JSON.stringify, the output may differ from the original payload and cause verification to fail. Always verify the payload exactly as received, byte-for-byte.

​
Missing the secret key

Each endpoint has a unique signing secret. Confirm you’re using the correct key for the endpoint receiving the webhook.

​
Sending the wrong response codes

A 2xx status code signals successful delivery regardless of what the response body contains. Return the appropriate status code so the system knows whether delivery succeeded or failed.

​
Responses timing out

Any endpoint that doesn’t respond within the timeout window is treated as a failed delivery. If your endpoint processes complex workflows, receive the message, enqueue it for async processing, and return 200 immediately.

​
Failure recovery

​
Re-enable a disabled endpoint

If all delivery attempts to an endpoint fail over a 5-day period, the endpoint is automatically disabled. To re-enable it, open the webhook portal, find the endpoint, and select Enable Endpoint.

​
Replay failed messages

Use replay when your service experienced downtime or an endpoint was misconfigured.
  • Single message: Find the message in the portal, open the options menu next to any attempt, and click Resend.
  • Bulk recovery: On the endpoint details page, select Options > Recover Failed Messages and choose a time window. For more precision, open the options menu on any message and select Replay all failed messages since this time.

Connection statuses

All connection and account status values

Document upload

Upload bills for processing and track job status

Sandbox testing

Test webhook events with mock data